houseplan-card/docs/specs/146-four-phase-sun-background.md

# Issue #146 — четырёхфазный фон «Следует за Солнцем»

Статус: **ТЗ на ревью**  
Дата: 2026-08-14  
Тип: `feature` · приоритет: `P1` · пользовательская ценность: 7/10 · сложность/риск: 8/10

Issue: [#146](https://github.com/Matysh/houseplan-card/issues/146)  
Ветка: `issue/146-four-phase-sun-background`  
Канонические документы: [SCOPE](../SCOPE.md), [SUN](../SUN.md),
[UX-MODES](../UX-MODES.md), [TOUCH-SUPPORT](../TOUCH-SUPPORT.md),
[ARCHITECTURE](../ARCHITECTURE.md),
[CONFIG-COMPATIBILITY](../CONFIG-COMPATIBILITY.md).

Текст issue имеет приоритет над приложенными к нему `SPECIFICATION.md`,
`README.md` и интерактивным прототипом. Решения владельца Q1–Q3 и все defaults
приняты 2026-08-14 в issue #146.

## 1. Сценарий и продуктовый контекст

Основная персона — человек, который ежедневно смотрит на дом в View либо на
настенной kiosk-панели и должен одним взглядом узнавать сам план и текущее
состояние дома. Фон вокруг плана даёт спокойный временной контекст, но не имеет
права искажать цвета пола, стен, Glow, устройств или других данных.

Это часть J1 из `docs/SCOPE.md`: House Plan существует прежде всего как
правдивый пространственный обзор дома. Новая функция декоративна, поэтому она
не становится единственным носителем состояния и не меняет доступность
управления. View и kiosk остаются полностью поддержанными touch-поверхностями.

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

**До:** режим `daynight` непрерывно интерполирует один сплошной цвет по высоте
Солнца, требует настроенный север, а ночью уменьшает яркость всего плана до
10 %. У новых установок и пространств режим не включён автоматически.

**После:** вокруг неизменного плана отображается одно из четырёх узнаваемых
окружений — рассвет, день, сумерки или ночь. Между фазами за 1100 ms плавно
меняются только градиент окружения, декоративный солнечный свет, внешняя
виньетка и alpha-aware контур плана. При доступном `sun.sun` состояние и свет
следуют реальному Солнцу; иначе работают по локальным часам браузера. Новые
установки и новые пространства начинают с режима «Следует за Солнцем», старые
неявные настройки сохраняют прежний статический вид.

## 3. Проблема и подтверждённая техническая база

1. `src/sun.ts::dayPhase()` возвращает непрерывный solid background,
   `planDim` и warmth. Это не четырёхфазная модель из issue.
2. Full card применяет ночной `brightness()` к `.zoomwrap`, поэтому вместе с
   окружением меняются сам план и все его live-слои.
3. `bg_mode: daynight` сейчас зависит от `north_deg` и валидного `sun.sun`;
   без компаса либо сущности молча возвращается статический фон.
4. `sunStateOf()` читает только azimuth/elevation. Направление движения
   (`attributes.rising`) ещё не участвует в выборе dawn/dusk.
5. Full card и `houseplan-space-card` рассчитывают фон разными render-путями,
   а editor canvases намеренно остаются статическими.
6. Текущий fallback отсутствующего `bg_mode` — `static`. Простая смена fallback
   на `daynight` изменила бы уже существующие планы без согласия пользователя.
7. Уже существуют независимые солнечные лучи из окон, Glow/spill, room fills,
   hover, decor/backdrop, vacuum и mode-transition #101. Новый фон должен
   интегрироваться с ними, а не заменить или перекрасить их.

## 4. Решения владельца

1. В диапазоне высоты между −6° и +6° признак
   `sun.sun.attributes.rising` различает рассвет и сумерки: rising — `dawn`,
   falling — `dusk`. Выше +6° — `day`, ниже −6° — `night`.
2. Если elevation или rising отсутствуют/некорректны, используется полный
   fallback по локальному времени браузера: dawn 05:00–07:59, day
   08:00–17:59, dusk 18:00–20:59, night 21:00–04:59.
3. При валидном `sun.sun` и фаза, и положение декоративного фонового света
   следуют реальным elevation/azimuth. Часовая дуга прототипа используется
   только при полном fallback. Ночью отдельный световой круг скрыт.
4. Существующие пространства без явного выбора сохраняют прежний статический
   вид через совместимую миграцию. Явный `daynight` получает новую
   четырёхфазную семантику. Новые установки и каждое новое пространство
   начинают с `daynight`; явный `static` автоматически не меняется.
5. Сам план не затемняется и не тонируется. Существующие Glow/spill, солнечные
   лучи из окон, room fills/hover, decor/backdrop, vacuum и остальные live-слои
   сохраняют действующее поведение.

## 5. Scope

В задачу входят:

1. дискретная модель `dawn | day | dusk | night` для `bg_mode: daynight`;
2. реальный sun-source с полным локальным clock-fallback;
3. четырёхфазный градиент окружения, декоративный солнечный свет, виньетка и
   alpha-aware контур по утверждённым visual tokens;
4. переход фаз за 1100 ms и `prefers-reduced-motion`;
5. одинаковая фаза и визуальные tokens в full View, kiosk и статической
   `houseplan-space-card`;
6. совместимость с mode-transition View ↔ editor из #101;
7. новый default для новой установки, ручного создания пространства и
   Floors/Areas onboarding;
8. однократная совместимая миграция старого неявного global default;
9. совместимость полного и per-space export/import;
10. обновление существующих RU/EN строк режима и подсказок;
11. unit, backend, production-bundle smoke, golden и performance coverage;
12. пользовательская/архитектурная документация, оба changelog и три
    поставляемые bundle-копии.

## 6. Non-scope

В задачу не входят:

- новый публичный mode token вместо `static | daynight`;
- ручной phase selector, видимый QA-control или пользовательское расписание;
- геолокация, внешний weather API, сетевой астрономический расчёт либо новые HA
  service calls/entities;
- изменение существующей геометрии/порогов/цвета солнечных лучей из окон;
- настройка visual palette, длительности перехода или порогов −6/+6 в UI;
- окрашивание, затемнение, насыщенность, opacity либо blend самого плана;
- day/night окружение внутри Plan/Devices/Decor editors;
- пересмотр бумажного слоя, room fill, Glow, hover, decor, vacuum,
  isometric/Labs или View ↔ editor UX;
- сохранение текущей вычисленной фазы в config/storage;
- canvas/WebGL только ради фонового градиента;
- production-обработка URL-параметра `?time=HH:MM`;
- изменение touch-контракта desktop-first редакторов.

## 7. Контракт источника и выбора фазы

### 7.1. Валидный real-sun sample

Для **окружения** real-sun sample валиден, только если одновременно:

- существует live-state `sun.sun`;
- `attributes.elevation` — конечное число;
- `attributes.azimuth` — конечное число, нормализуемое в `[0, 360)`;
- `attributes.rising` — настоящий boolean.

Если любое условие нарушено, весь day-cycle — и фаза, и положение фонового
света — атомарно переходит на clock-fallback. Нельзя смешивать фазу от часов с
позицией из частично валидного `sun.sun`.

Это отдельная проверка только для окружения. Действующий `sunStateOf()` и
существующие оконные лучи продолжают использовать azimuth/elevation по
`docs/SUN.md`: отсутствие `rising` не должно выключить уже работающие лучи.

### 7.2. Фаза по реальному Солнцу

Границы детерминированы так:

| Условие | Фаза |
|---|---|
| `elevation <= -6` | `night` |
| `-6 < elevation < 6` и `rising === true` | `dawn` |
| `elevation >= 6` | `day` |
| `-6 < elevation < 6` и `rising === false` | `dusk` |

На точной верхней границе состояние уже `day`, на точной нижней — уже `night`.
Azimuth wrap 359°→0° не меняет фазу.

### 7.3. Полный clock-fallback

Используются часы и часовой пояс браузера через локальный `Date`, без серверного
времени:

| Локальные минуты | Фаза |
|---|---|
| `300 <= m < 480` (05:00–07:59) | `dawn` |
| `480 <= m < 1080` (08:00–17:59) | `day` |
| `1080 <= m < 1260` (18:00–20:59) | `dusk` |
| иначе (21:00–04:59) | `night` |

DST и смену часового пояса даёт платформа `Date`. Интервал проверяет часы
каждые 30 s только пока используется fallback и вкладка видима. Дополнительно
состояние пересчитывается до первого видимого кадра, при `pageshow` и при
`visibilitychange` обратно в `visible`. Если фаза и позиционные tokens не
изменились, Lit/DOM update не запрашивается.

### 7.4. Переключение источника

Появление, исчезновение либо восстановление валидности `sun.sun` пересчитывает
весь day-cycle из одного snapshot. Текущая фаза не хранится как истина и не
может остаться от прежнего источника. Обычная смена источника получает тот же
1100 ms environment transition; fresh mount сразу начинает с правильного
состояния без вспышки default-day.

## 8. Контракт декоративного фонового света

Декоративный свет — pointer-inert слой окружения под планом. Он не является
оконным солнечным лучом и не использует `north_deg`: фон существует независимо
от ориентации дома.

### 8.1. Real-sun position

При валидном real-sun sample позиция вычисляется из реальных атрибутов:

```text
x = 50 - sin(azimuth * pi / 180) * 42       // percent
y = 78 - clamp(elevation, 0, 90) / 90 * 64 // percent
opacityFactor = clamp((elevation + 6) / 12, 0, 1)
```

Так восток (около 90°) оказывается у левого горизонта, запад (около 270°) — у
правого, а северный и южный полдень проходят через центр без зависимости от
полушария. Отрицательная высота держит свет у горизонта; в `night` opacity
принудительно равна нулю.

### 8.2. Clock-fallback arc

Fallback повторяет дугу прототипа:

```text
progress = (minutes - 300) / (1260 - 300)
x = 8 + progress * 84
y = 78 - sin(progress * pi) * 64
opacityFactor = max(.18, min((minutes - 300) / 120,
                             (1260 - minutes) / 120, 1))
```

Формулы применяются только в диапазоне 05:00 ≤ time < 21:00; вне его opacity
равна нулю. Позиция обновляется той же 30-секундной fallback-проверкой, не
пересчитывая план, стены, room geometry или устройства.

### 8.3. Вид и слой

Свет — мягкий radial gradient без жёсткой окружности, размером 250 CSS px в
эталонном desktop layout; на меньшей поверхности он ограничивается размером
окружения и не создаёт overflow/scroll. Цвет задаётся фазой, позиция и opacity —
источником выше. В `night` элемент может оставаться в DOM, но его вычисленная
opacity обязана быть 0 и ни один видимый световой круг не допускается.

## 9. Визуальный контракт четырёх фаз

Окружение строится из вертикального linear gradient и мягкого radial horizon у
нижней части сцены. Значения ниже — канонические tokens прототипа; отклонение
требует нового решения владельца, а не локального «подбора на глаз».

| Фаза | top | bottom | horizon | sun | vignette |
|---|---|---|---|---|---|
| `dawn` | `#aabdd1` | `#e8c8b7` | `rgba(255,201,156,.56)` | `rgba(255,188,125,.78)` | `rgba(65,72,99,.21)` |
| `day` | `#dce9ef` | `#cbdce3` | `rgba(255,245,220,.45)` | `rgba(255,239,190,.72)` | `rgba(65,91,105,.16)` |
| `dusk` | `#48536c` | `#9a7380` | `rgba(242,156,114,.34)` | `rgba(255,167,113,.55)` | `rgba(20,26,44,.39)` |
| `night` | `#111a27` | `#1f2f3e` | `rgba(79,120,151,.16)` | transparent | `rgba(3,8,14,.58)` |

Alpha-aware контур применяет три zero-offset `drop-shadow` либо визуально
эквивалентный эффект к **одному каноническому plan-paper composite**, не к
каждой комнате/стене отдельно:

| Фаза | near `0 0 1px` | mid `0 0 5px` | far `0 0 10px` |
|---|---|---|---|
| `dawn` | `rgba(74,57,61,.25)` | `rgba(255,238,224,.40)` | `rgba(255,224,202,.18)` |
| `day` | `rgba(45,62,71,.28)` | `rgba(255,255,255,.42)` | `rgba(255,255,255,.20)` |
| `dusk` | `rgba(238,219,225,.40)` | `rgba(229,207,218,.26)` | `rgba(215,190,205,.12)` |
| `night` | `rgba(218,238,249,.56)` | `rgba(174,215,238,.30)` | `rgba(136,194,226,.14)` |

Контур повторяет внешний alpha-контур общего бумажного footprint, не имеет
смещения, не создаёт внутренних швов между комнатами и не обводит устройства,
labels, hover или live-эффекты. Для image-plan канонический footprint — его
действующий opaque paper rect; для drawn-plan — объединённая по одному group
совокупность room paper polygons. Пустой drawn space без комнат не получает
ложный прямоугольный контур.

## 10. Инвариант неизменного плана

Во всех четырёх фазах к plan/content tree запрещено добавлять:

- `brightness`, `contrast`, `saturate`, `sepia`, `hue-rotate` или иной
  color filter;
- opacity родителя, `mix-blend-mode` или цветной overlay поверх плана;
- смену paper/floor/room fill цвета из-за фазы;
- изменение яркости/цвета devices, labels, decor/backdrop, vacuum, Glow/spill,
  hover или оконных солнечных лучей.

Действующий `dayPhase().planDim` удаляется из day-cycle render и из target
brightness mode-transition #101. Plan pixels внутри plan-paper alpha footprint
до и после смены фазы должны совпадать; разрешено меняться только внешнему
zero-offset outline за границей footprint.

## 11. Переходы и surfaces

### 11.1. Phase transition

При смене фазы ровно 1100 ms с easing
`cubic-bezier(.22, .61, .36, 1)` анимируются только:

- environment top/bottom/horizon;
- цвет/позиция/opacity декоративного света;
- внешняя vignette;
- три цвета alpha-aware outline.

Нельзя fade всего экрана или самого плана. Реализация обязана использовать
действительно интерполируемые CSS primitives либо environment-layer crossfade;
простая декларация `transition` на неанимируемом gradient не считается
выполнением. При `prefers-reduced-motion: reduce` длительность практически
нулевая (`<= 0.01 ms` либо `transition: none`).

### 11.2. Full View, kiosk и static card

Full View и kiosk используют один environment model. Статическая
`houseplan-space-card` получает ту же effective phase, palette, свет, outline и
fallback lifecycle; оконные wedges в static card не добавляются — действующее
ограничение `docs/SUN.md` сохраняется.

### 11.3. Editors и #101

Plan/Devices/Decor editors сохраняют действующий editor background и не
получают четырёхфазное окружение. При View ↔ editor переходе #101:

1. исходный и целевой кадр используют один атомарный phase/source snapshot;
2. сам plan composite не меняет brightness/color;
3. environment transition не перехватывает pointer/focus и не оставляет
   скрытый слой после commit/cancel;
4. при возвращении в View актуальная фаза пересчитывается до целевого кадра,
   включая возврат после долгой паузы.

### 11.4. Существующие live-эффекты

Glow/spill, room fills/hover, decor/backdrop, vacuum, labels/devices и оконные
лучи сохраняют порядок слоёв, opacity, blend и lifecycle. `north_deg` продолжает
управлять только ориентационно зависимыми оконными лучами; `daynight` background
больше не выключается из-за отсутствия компаса.

## 12. Модель данных, defaults, migration и import/export

### 12.1. Persisted schema

Публичная schema не расширяется: global и per-space
`settings.bg_mode: 'static' | 'daynight'`, per-space null/absence = inherit.
Вычисленная фаза, источник и позиция света не сохраняются. Backend продолжает
принимать отсутствие `bg_mode` ради legacy compatibility.

Runtime fallback отсутствующего effective token остаётся `static`; новая
семантика достигается материализованными defaults, а не переопределением
отсутствующего поля.

### 12.2. Новая установка и новые пространства

- Новый `DEFAULT_CONFIG` материализует global `settings.bg_mode: 'daynight'`.
- Ручное Create space материализует per-space `bg_mode: 'daynight'`.
- Каждое пространство, созданное Floors/Areas onboarding, материализует
  per-space `bg_mode: 'daynight'`.
- Открытие и сохранение существующего space dialog не меняет его mode без
  действия пользователя.
- Явный `static` на любом уровне никогда не переписывается автоматически.

Per-space materialization нужна даже при новом global default: добавленное
позднее пространство начинает с `daynight`, в том числе внутри старой
установки, чей global default мигрирован в `static`.

### 12.3. Однократная миграция существующего store

Backward-compatible storage migration выполняется один раз и идемпотентно:

1. если в существующем config global `settings.bg_mode` отсутствует либо
   невалиден, он материализуется как `static`;
2. валидный global `static` или `daynight` сохраняется;
3. все валидные per-space overrides сохраняются без переписывания;
4. spaces без override продолжают наследовать уже материализованный global;
5. migration сохраняет неизвестные поля, не меняет layout и не создаёт
   config-update storm;
6. повторный старт не создаёт новую запись/revision.

### 12.4. Export/import

- Full export после миграции содержит явный global mode; legacy full import без
  него материализуется как `static` до preview/apply.
- Per-space export материализует в экспортируемом space его **effective** mode,
  чтобы перенос не зависел от отсутствующего global settings блока.
- Legacy per-space import без mode материализуется как `static` до merge.
- Явные `static`/`daynight` сохраняются при same-instance и foreign import.
- Import preview показывает тот же итоговый mode, который будет применён;
  preview не пишет storage.
- Никакой импорт не превращается в «новое пространство по default»:
  импортированная семантика имеет приоритет над default ручного Create.

## 13. UX, i18n, accessibility и touch

Видимых новых controls нет. Действующий selector остаётся двухпозиционным:
`static` и `daynight`; color picker виден только для `static`.

Обновляются существующие RU/EN keys без добавления третьего режима:

- `gs.bg_daynight`: «Следует за Солнцем» / “Follows the Sun”;
- `gs.bg_daynight_hint`: четыре фазы, real sun и локальный fallback, без
  требования компаса;
- `gs.sun_missing` и `gs.north_hint`: отсутствие sun/севера отключает оконные
  лучи, но не clock-driven background.

Фаза декоративна: она не добавляет announcement, focus target, toast или
semantic state; не меняет размеры сцены и не служит единственным носителем
информации. `forced-colors` сохраняет функциональную читаемость plan/devices;
декоративные environment layers могут быть упрощены либо отключены.

View, kiosk и static card полностью поддерживаются мышью, touch и без pointer:
новые слои имеют `pointer-events: none`, не перехватывают tap/swipe/pinch и не
меняют hit targets. Editor остаётся desktop-first и не получает новых действий.

## 14. Архитектурный и performance-контракт

1. Один pure resolver возвращает phase, source (`sun | clock`) и декоративные
   position/opacity tokens. Full/static surfaces не копируют пороги и формулы.
2. Palette хранится одной typed таблицей. CSS и тесты не получают расходящиеся
   hard-coded варианты.
3. Real-sun resolver запускается только на релевантном изменении sun snapshot,
   config/space или lifecycle catch-up; прочие `hass` ticks не меняют DOM.
4. Clock timer существует только в fallback, не чаще 30 s, не выполняет
   необязательную работу в hidden document и очищается в `disconnectedCallback`.
5. Не создаётся `requestAnimationFrame` loop, canvas/WebGL, geometry/layout
   polling, новая сеть, service call или storage write.
6. Phase/source/position update меняет только bounded environment state/style.
   Rooms, walls, openings, Glow barriers, devices и backdrop geometry не
   пересчитываются.
7. Alpha-aware outline применяется к одному plan-paper composite; per-room
   filter multiplication запрещён.
8. Environment DOM count постоянен относительно rooms/devices и не растёт при
   каждой фазе или visibility cycle.
9. #101 и cold-start #131 сохраняют первый полный кадр: не допускается второй
   пустой render ради вычисления локального времени.
10. Таргетированный performance smoke доказывает отсутствие geometry/device
    rebuild на clock tick и обычном нерелевантном hass tick. Перед бетой на
    exact SHA обязательны существующие performance smoke и Full Performance без
    ослабления budgets.

## 15. Acceptance criteria

- **AC1 (`unit`; разработчик):** real-sun resolver детерминированно выдаёт
  `night/dawn/day/dusk` на обеих сторонах −6/+6, точных границах, при rising и
  falling; azimuth wrap не меняет фазу.
- **AC2 (`unit` + production-bundle smoke; разработчик):** отсутствие/garbage
  любого из elevation/azimuth/rising атомарно включает clock-fallback с точными
  границами 05:00/08:00/18:00/21:00; валидность real sample восстанавливает весь
  sun-source без смешивания данных.
- **AC3 (`unit` + targeted smoke; разработчик):** real-sun позиция следует
  elevation/azimuth, fallback — утверждённой дуге 05:00→13:00→21:00, а night
  имеет opacity 0. Ни один update не пересчитывает plan geometry.
- **AC4 (`golden` + computed-style smoke; владелец/ревьюер):** dawn/day/dusk/
  night используют точные palette и outline tokens раздела 9; ночью нет
  видимого светового круга, а светлый дневной и тёмный ночной план отделены от
  окружения.
- **AC5 (`pixel regression` + code review; разработчик/ревьюер):** внутри
  plan-paper footprint пиксели plan, floors, room fills, Glow/spill,
  devices/labels, decor/backdrop, vacuum, hover и оконных лучей совпадают между
  четырьмя фазами; никакой phase-dependent plan filter/opacity/blend не остаётся.
- **AC6 (`targeted smoke`; разработчик):** смена фазы анимирует только environment
  и outer outline за 1100 ms с заданным easing; plan не мигает. Reduced motion
  завершает переход практически мгновенно.
- **AC7 (`production-bundle smoke` + golden; разработчик/владелец):** full View,
  kiosk и static card получают одну effective phase/palette; editors остаются
  прежними, а #101 transition не оставляет stale/interactive environment layer.
- **AC8 (`unit` + smoke; разработчик):** `daynight` работает без `north_deg` и
  без `sun.sun` через clock fallback; оконные лучи по-прежнему требуют свои
  действующие sun/north gates и не меняют геометрию/пороги.
- **AC9 (`backend migration tests`; разработчик):** существующий отсутствующий
  global mode мигрирует в `static` ровно один раз; валидные global/per-space
  modes и неизвестные поля сохраняются; повторный старт не пишет store/rev.
- **AC10 (`frontend unit` + `backend/import tests` + smoke; разработчик):** новая
  установка, manual Create и Floors/Areas create материализуют `daynight`;
  существующий Edit не меняет mode сам; явный `static` остаётся static.
- **AC11 (`backend/import-export tests`; разработчик):** full/space export и
  legacy/current import выполняют контракт §12.4, preview совпадает с apply, а
  preview не пишет storage.
- **AC12 (`i18n test` + accessibility/touch smoke; разработчик):** RU/EN тексты
  описывают четыре фазы и fallback; environment pointer-inert, не двигает focus,
  не меняет размеры/hit targets и не ломает tap/swipe/pinch в View/kiosk.
- **AC13 (`lifecycle smoke`; разработчик):** fallback пересчитывается сразу,
  каждые 30 s только в visible state, на `pageshow` и visible-return; timer и
  listeners очищаются при disconnect, повторное подключение не дублирует их.
- **AC14 (`performance smoke` + code review; разработчик/ревьюер):** sun/clock
  update меняет bounded environment state без room/device/geometry rebuild,
  RAF-loop, canvas, сети, HA calls или storage writes; DOM/timer count bounded.
- **AC15 (`typecheck` + `unit` + `build` + docs review; разработчик):** локальные
  implementation gates зелёные, обе пользовательские документации/changelog и
  три bundle-копии обновлены в одном `User-Visible: yes` коммите.
- **AC16 (`exact-SHA Linux gates`; Claude/релиз-инженер):** перед бетой зелёны
  Validate, полный smoke, reviewed golden и Full Performance на одном SHA без
  ослабления budgets; security/network/schema verdict явно записан в code review.

## 16. План автотестов и визуального review

### 16.1. Unit/frontend

Добавить pure-helper coverage:

1. elevation `-6.1/-6/-5.9/5.9/6/6.1` при обоих rising values;
2. NaN/infinity/string/missing для elevation, azimuth и rising;
3. fallback минуты `299/300/479/480/1079/1080/1259/1260`;
4. real position east/south/west/north и elevation below horizon/0/45/90;
5. fallback position/opacity в 05:00, 07:00, 13:00, 19:00, 21:00;
6. palette completeness и night opacity 0;
7. mode inheritance с compatibility fallback `static`;
8. отсутствие влияния нового rising requirement на sun-ray helpers.

### 16.2. Backend и compatibility

Покрыть storage migration: missing, static, daynight, mixed per-space,
malformed legacy, unknown fields, idempotent second load и rev/event count.

Расширить import/export matrix: legacy full/space без mode, current full/space с
обоими modes, inherited export materialization, same/foreign source, preview
versus apply и import into target с противоположным global mode.

### 16.3. Targeted production-bundle smoke

Обновить sun/background smoke либо добавить отдельный four-phase smoke на
собранном bundle:

1. full View, kiosk и `houseplan-space-card` проходят четыре deterministic
   real-sun phase;
2. отдельная matrix проходит clock fallback и source recovery;
3. computed styles проверяют palette, outline, light visibility и transition;
4. pixel probes/masked screenshots доказывают неизменность plan interior;
5. existing window rays работают с north, а background — без north;
6. editor и View↔editor transition не получают stale layer;
7. visibility/pageshow/timer cleanup и reduced motion проверяются под fake clock;
8. manual/Floors create и existing Edit проверяют persisted modes;
9. counters доказывают отсутствие geometry/device rebuild и storage/network
   activity на fallback tick.

Targeted smoke пишется вместе с кодом; полный smoke-suite запускается перед
бетой, не в implementation loop.

### 16.4. Golden

Нужны новые deterministic Linux golden-сцены full View для `dawn`, `day`,
`dusk`, `night` и static-card сцены для двух контрастных крайних состояний
`day/night`. Одинаковые fixture plan/live state/camera исключают посторонний
diff; reduced motion включён.

Golden artifact ревьюится владельцем/Claude как единый набор: соответствие
прототипу, отсутствие plan tint/dim, световой круг не виден ночью, outline не
создаёт per-room seams. Baseline принимается только штатной командой
`golden:accept -- --reviewed` из полного Linux-артефакта и отдельным коммитом с
обязательными release/baseline trailers по runbook; принять baseline ради
зелёного CI нельзя.

## 17. План реализации

1. Ввести typed day-cycle resolver/palette рядом с sun pure logic, не меняя
   оконную ray geometry.
2. Подключить единый environment model и lifecycle к full/static surfaces;
   убрать phase-dependent plan dim и compass gate background.
3. Реализовать environment layers, decorative light, vignette, composite
   outline, 1100 ms/reduced-motion и интеграцию #101.
4. Материализовать новые defaults, storage migration и import/export
   compatibility.
5. Обновить selectors/hints i18n, документацию и changelog.
6. Добавить unit/backend/targeted production-bundle smoke и deterministic
   golden scenes.
7. Выполнить implementation-loop `typecheck`, `unit`, `build`; остальные гейты
   — на пре-релизе по команде владельца.

Точные имена helper-функций, CSS classes и private fields не являются
продуктовым контрактом.

## 18. Release-артефакты

Изменение пользовательское: implementation-коммит имеет `User-Visible: yes` и
в том же коммите обновляет:

- `docs/CHANGELOG.md` и `docs/CHANGELOG.ru.md`;
- `docs/SUN.md` — новый источник истины по фазам, fallback, визуалу и
  независимости от компаса;
- `docs/USER-GUIDE.ru.md` — выбор режима, четыре фазы, defaults и fallback;
- `docs/ARCHITECTURE.md` — resolver/lifecycle/layers и full/static parity;
- `docs/CONFIG-COMPATIBILITY.md` — storage/default/import migration;
- `docs/TESTING.md` — targeted smoke/golden matrix;
- RU/EN i18n и три поставляемые bundle-копии.

Перед бетой на exact SHA обязательны:

- Linux Validate;
- полный smoke-suite;
- reviewed/accepted golden artifact без необъяснённого diff;
- performance smoke и Full Performance без ослабления budgets;
- code review с явным negative security/network/HA-call verdict.

Новый отдельный security report не требуется: feature не принимает HTML/URL,
не добавляет network/storage input или HA action. Публикация проходит через
обычную бету до stable; issue закрывает владелец пачкой после опубликованной беты.

## 19. Риски и меры

| Риск | Вероятность / влияние | Мера |
|---|---|---|
| План незаметно остаётся dim/tinted старым filter | средняя / высокая | AC5 pixel mask, удаление planDim consumers, four-phase golden |
| Старый план без mode внезапно включит daynight | средняя / высокая | materialized storage migration в static, idempotence/backend tests |
| Новое пространство в старой установке наследует static | высокая / средняя | explicit per-space daynight в manual и Floors create, AC10 |
| Partial sun sample смешивается с clock position | средняя / средняя | атомарный resolver/source, garbage matrix AC2 |
| CSS gradient прыгает вместо перехода | средняя / средняя | проверяемые intermediate styles/pixels, animatable primitive/crossfade |
| Outline создаёт швы по комнатам или обводит devices | средняя / высокая | один plan-paper group, full/static golden и DOM assertion |
| 30 s timer течёт/дублируется | средняя / средняя | fallback-only lifecycle, disconnect/reconnect smoke |
| Background начинает зависеть от north и молчит | средняя / высокая | отдельные gates background/rays, no-north smoke |
| #101 оставляет stale слой либо pointer blocker | средняя / высокая | mode-transition targeted smoke, pointer-events none |
| Import наследует target mode вместо исходного | средняя / высокая | effective space export + legacy import materialization matrix |
| Visual layers ухудшают слабое устройство | низкая / высокая | bounded layers, один outline filter, performance exact-SHA gates |

## 20. Откат

Пользовательский немедленный откат — выбрать `static` глобально либо для
пространства; environment timer/layers становятся инертны без потери данных.

Технический откат — revert implementation-коммита вместе с тестами,
документацией, changelog и bundle-копиями. Миграция только материализует ранее
эффективный `static`, поэтому старая версия полностью читает результат; новые
явные `daynight` также являются старым валидным token. Обратная миграция и
удаление полей не нужны. Если default новой установки требуется временно
отключить без полного revert, вернуть creation defaults в `static`; сохранённые
пользовательские choices не переписывать.

## 21. Принятые технические предположения — можно менять без продуктового ревью

1. Точная граница считается `<= -6 => night`, `>= 6 => day`; только открытый
   интервал различает rising/falling.
2. Environment использует отдельный strict real-sun validator; ray API не
   расширяется обязательным `rising`.
3. Real decorative position использует формулы §8.1: horizontal проекция через
   `sin(azimuth)`, vertical — линейно по положительной elevation. Это
   декоративное отображение, не плановая координата и не зависит от north.
4. Размер light можно выразить через bounded `clamp()` вместо ровно 250 px на
   маленьких карточках, сохранив desktop reference и visual intent.
5. Конкретный способ плавной смены gradient — registered custom properties или
   два bounded environment layers; AC важнее механизма.
6. QA не читает production `?time`: fake clock/sun внедряется только в unit,
   demo и smoke harness. Пользовательского QA-control нет.
7. Storage migration рекомендуется реализовать bump minor version с проверкой
   формы config-store document; точный helper свободен при соблюдении AC9.
8. Per-space export может материализовать effective mode в копии export payload,
   не меняя live config.
9. Один shared fallback ticker допустим вместо timer на карточку, если lifecycle,
   isolation нескольких карточек и bounded listener count доказаны тестами.
10. DOM может хранить фазу как `data-day-cycle` либо typed class; публичной
    schema/DOM API это не становится.
11. Контур строится вокруг действующего канонического opaque paper composite:
    image rect либо общего group room papers; новый анализ alpha пикселей
    загруженного raster-файла не требуется.
12. Открытых продуктовых вопросов нет; все Q1–Q3 и defaults приняты владельцем
    2026-08-14.