houseplan-card/docs/specs/471-isometric-overlay-white-plates.md

#471 — Убрать видимые raised plates вокруг элементов изометрического View

• Issue: https://github.com/Matysh/houseplan-card/issues/471
• Тип / приоритет: bug + polish / P1
• Трек: полный; задача отменяет явно принятый UX-контракт Stage 3 из #160, поэтому не проходит критерий лёгкого трека «нет нового или изменённого UX-контракта»
• Оценка: пользовательская ценность 8/10; ценность для архитектуры 7/10; сложность 4/10; риск 4/10
• Связано: #89, #122, #160; docs/ISOMETRIC.md, docs/adr/160-isometric-stage3-overlays.md

1. Сценарий

Персона — Home admin из docs/SCOPE.md, который тестирует скрытый изометрический режим в полном House Plan View на desktop, wall tablet либо телефоне. Момент — план со множеством устройств и подписей комнат целиком вписан в доступную область, поэтому белые подложки поднятых элементов занимают заметную долю изображения и перекрывают архитектуру.

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

До: вокруг маркеров видны дополнительные белые квадраты, а под длинными названиями комнат — широкие белые полосы, пересекающие пол и стены.

После: остаются сами маркеры с их штатными компактными подложками и обычный текст комнаты; дополнительного прямоугольного фона вокруг полного габарита элемента нет.

3. Подтверждённая причина и заменяемый контракт

Артефакт является намеренной частью Stage 3, а не браузерной ошибкой:

• ISO_RAISED_FOOTPRINT и isoRaisedOverlayHalfSize() в src/iso-scene-render.ts вычисляют консервативный габарит для device, room-label и opening-lock;
• resolveIsoOverlayPlacement() в src/iso-overlays.ts проецирует этот габарит и использует его для wall collision, nudge и tether policy;
• renderIsoRaisedOverlays() рисует тот же габарит как SVG polygon;
• .iso-overlay-plate в src/styles/plan.styles.ts имеет почти непрозрачную светлую заливку rgba(248, 249, 247, 0.9);
• room footprint резервирует worst-case ширину всех включённых метрик, а device footprint — auxiliary extent, даже если фактическое содержимое короче;
• golden demo/golden/baselines/isometric-stage3-overlays-light.png и contract/smoke тесты сейчас закрепляют наличие видимого polygon.

Первый коммит с поведением — ee7d4869 из #160. D3 и AC4 исходного ТЗ #160, ADR и текущий docs/ISOMETRIC.md называют эту поверхность raised plate.

#471 заменяет только визуальную часть этого решения: консервативная геометрия остаётся невидимым collision/fit footprint, но больше не является декоративной поверхностью. Сам raised plane, координаты и интерактивность не отменяются.

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

В изометрическом View ни у одного поднятого overlay нет отдельной видимой floor-parallel подложки по его общему прямоугольному габариту.

Единое правило применяется к:

1. device marker целиком;
2. room name и room metrics card;
3. opening lock marker.

Штатные собственные поверхности содержимого не относятся к удаляемой plate:

• shell/core маркера устройства;
• value badge, LQI и прочие satellite badges;
• компактная поверхность lock marker;
• focus/selection/hover affordance, определённые самим интерактивным root.

Grounding shadow и tether остаются. Консервативный footprint остаётся невидимой расчётной геометрией для collision, nudge, fit/home и room fit.

5. Скоуп

1. Прекратить вывод видимых SVG plate и plate texture для всех трёх raised overlay kinds.
2. Сохранить footprint и все потребляющие его placement/bounds алгоритмы без числового изменения результата.
3. Развести в именовании и документации невидимый footprint и удалённую декоративную plate, чтобы safety envelope нельзя было снова принять за пользовательскую поверхность.
4. Удалить ставшие неиспользуемыми plate styles и overlay texture definition; grounding shadow definition сохранить.
5. Переписать contract/unit/browser доказательства, которые сейчас требуют видимый polygon.
6. Переснять затронутые изометрические golden только через независимое Linux acceptance по общему процессу.
7. Актуализировать текущие внутренние документы Stage 3.

6. Не входит

• изменение высоты raised plane, камеры 4°/20°, wall height или visual offset;
• изменение размеров консервативного footprint;
• новое измерение фактического DOM, ResizeObserver либо layout read-loop;
• изменение wall collision, owner selection, nudge direction/cap или tether visibility rules;
• удаление grounding shadow либо tether;
• новый фон, text shadow, blur, outline или другая замена белой plate;
• редизайн shell/core, badge, room typography либо opening lock;
• изменение z-order, Zigbee topology, Glow, sunlight, vacuum и opening volume;
• новые настройки, schema/config/layout/storage поля, миграция либо i18n;
• публичное включение изометрического режима;
• изменение Flat, редакторов или houseplan-space-card.

Если читаемость конкретного текста без общей подложки окажется недостаточной, альтернативный локальный text treatment требует отдельного продуктового решения и не добавляется в #471 попутно.

7. Контракт невидимого footprint

Для каждого raised overlay по-прежнему вычисляются:

1. неизменная логическая floor-точка;
2. projected floor point;
3. raised point до nudge;
4. консервативный screen-facing footprint на raised plane;
5. конечный visual point и тот же footprint после nudge;
6. grounding и tether geometry.

Footprint не попадает в SVG/HTML как закрашенная или обведённая поверхность и не создаёт собственный stacking/paint artifact. Он остаётся входом для:

• пересечения с canonical wall silhouettes и safety gap;
• bounded inward nudge;
• nearWallBefore / nearWallAfter и tether visibility;
• isoOverlaySceneBounds();
• стабильного resolveIsoOverlayFitEnvelope() для fit/home и room fit.

Удаление декора не должно менять ни одну координату либо boolean/status placement result на одинаковом входе. Переименование внутренних полей plate* в footprint* предпочтительно и не является изменением модели данных.

8. Контракт рендера и композиции

iso-overlays-svg сохраняется как inert слой для grounding и tether. В нём не должно быть .iso-overlay-plate, .iso-overlay-plate-texture либо эквивалентной залитой/обведённой геометрии footprint.

Порядок остаётся прежним:

1. floor/live content;
2. structural walls/openings;
3. grounding/tether cues;
4. screen-facing HTML markers/labels/locks;
5. системные tooltip/dialog/chrome.

HTML roots продолжают получать один и тот же visualScene. Их role, tabindex, accessible name, pointer/keyboard handlers, hit target и CSS собственных элементов не меняются.

layers.materialNuance больше не создаёт overlay texture pattern, потому что допустимой поверхности для него нет. layers.shadows продолжает управлять только grounding shadow. Ошибка decorative capability не должна переводить сцену в Flat.

9. Режимы, состояния и graceful degradation

• Light/dark theme используют одно правило «без plate».
• Forced colors не возвращает fill: Canvas вокруг overlay; собственные нативные поверхности marker/lock продолжают существующий forced-colors контракт.
• No-filter скрывает grounding nuance как раньше, но не меняет наличие содержимого.
• Reduced motion ничего не меняет в конечном кадре; новой анимации нет.
• Kiosk и coarse pointer показывают тот же результат, сохраняя минимум 44×44 px у интерактивного HTML root.
• show_borders:false по-прежнему полностью отключает raised placement, grounding и tether и возвращает overlays к floor anchor.
• Flat, Plan/Devices/Background editors и static card не получают изменений DOM либо CSS.

10. UX и доступность

Новых контролов, жестов, подсказок и текстов нет. Изменение только убирает визуальный шум. Room fit/Area link, device click/context action и opening-lock semantics остаются действующими.

Invisible footprint, grounding и tether не получают role, accessible name, tab stop или pointer events. Focus ring принадлежит исходному HTML root и не зависит от удалённой plate.

11. Модель данных, совместимость и i18n

Config, layout, backend stores, schema version, export/import и localStorage не меняются. Миграции и downgrade converter отсутствуют.

Внутреннее переименование поля placement не сериализуется и не является compatibility surface. Старый frontend после downgrade прочитает те же данные и снова покажет прежнюю plate.

Новых или изменённых строк нет; словари EN/RU/DE/FR не меняются.

12. Производительность и lifecycle

• Structural fingerprint, LRU cap 8 и cache invalidation остаются прежними.
• HA state, hover/focus, pan/zoom и opening update не начинают перестраивать structural scene либо читать layout.
• Удаляются до двух SVG polygon на raised overlay и один неиспользуемый shared texture pattern; DOM/paint объём может только уменьшиться.
• Footprint/nudge computation сохраняет прежнюю сложность и кэширование.
• Initial Flat graph и alpha lazy boundary не меняются.
• Новый performance profile не нужен; существующие Stage 3 counts, bundle:budget и точечный isometric smoke не должны регрессировать.

13. Security и privacy

Новых API, URL, persistence, HA service call или пользовательского HTML нет. Удаляемая геометрия уже pointer/ARIA-inert; после исправления существующие interactive roots остаются единственными владельцами действий.

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

AC1 — видимый результат (browser raster + reviewed golden)

В light и dark изометрическом View отсутствует дополнительный прямоугольный или квадратный фон вокруг device, room label/card и opening lock. Длинное имя комнаты при fit/home и минимальном масштабе не создаёт белую полосу через стены. Штатные shell/core/badges/lock surfaces остаются.

AC2 — отсутствие скрытых визуальных fallback (contract + smoke)

Raised SVG не содержит .iso-overlay-plate, plate texture либо эквивалентной painted footprint geometry при material nuance on/off, forced colors и unsupported filter. Возврат одного непрозрачного polygon делает защитный тест красным.

AC3 — placement parity (unit exact matrix)

На одинаковых fixtures до/после исправления совпадают floor/raised/visual anchors, footprint points, nudge vector/distance, near-wall flags, status, reason, tether и grounding для device, room-label и opening-lock.

AC4 — fit и границы (unit + browser smoke)

isoOverlaySceneBounds, fit/home и room fit продолжают учитывать невидимый footprint и полный screen-facing root. Конечный viewBox и позиция элементов не меняются только из-за удаления декора; длинные/короткие имена и 0/часть/все room metrics не клипуются.

AC5 — interaction и touch (browser smoke)

Device hover/focus/click/context action, room click/Area link, lock action и 44×44 px target работают по прежним roots. Ground/tether/footprint не перехватывают pointer. Kiosk/coarse pointer сохраняют View safety floor.

AC6 — режимы и соседние слои (contract + browser smoke)

show_borders:false возвращает floor placement без raised subtree; Flat, редакторы и static card не меняются. Zigbee topology endpoints продолжают совпадать с фактическими поднятыми marker positions.

AC7 — data/performance contract (unit + source contract)

Нет новых config/layout/storage/i18n/network/service полей. Structural fingerprint/build count и LRU не меняются; overlay material definition count и polygon count уменьшаются, а bundle остаётся в действующем бюджете.

AC8 — документация и артефакты (review)

docs/ISOMETRIC.md, ADR #160 и исходное ТЗ #160 явно отмечают superseding решение #471: plate как видимая поверхность удалена, footprint как расчётная геометрия сохранён. Затронутые golden приняты независимым reviewer из полного Linux artifact.

15. План автотестов и red witnesses

Unit/contract

1. Обновить test/iso-overlays.test.mjs: footprint остаётся четырёхугольником, а все placement outputs для free/near-wall/nudged/degraded/no-borders fixtures сохраняются.
2. Обновить test/iso-scene-render.test.mjs: footprint по-прежнему учитывает device auxiliaries и room metrics; scene/fit bounds используют его без видимого renderer.
3. Обновить test/isometric-contract.test.mjs: запретить plate selectors, polygons и overlay texture definition; сохранить raised root, grounding, tether, forced-colors и 44 px contracts.
4. Проверить material definition count без orphan hp-iso-overlay-texture.

Browser smoke

Расширить demo/smoke_isometric_contract.mjs и при необходимости demo/smoke_isometric_live_touch.mjs:

• dense device set и room label с 0/частью/всеми метриками;
• отсутствие painted footprint в обычном, dark, forced-colors и no-filter;
• неизменные centres/nudge/tether/bounds;
• fit/home и room fit без клиппинга;
• pointer/keyboard/coarse-pointer actions и 44 px target;
• topology endpoint следует фактическому marker root.

Golden

Переснять только действительно изменённые Iso Stage 3 кадры. Flat baselines должны остаться byte/pixel unchanged. Обязателен плотный общий кадр с длинными названиями и несколькими типами marker; возвращённая непрозрачная plate должна создавать заметный diff.

Golden acceptance выполняет только независимый reviewer через npm run golden:accept -- --reviewed на полном Linux CI artifact с provenance.

Red witnesses

Witness	Искусственная поломка	Обязательный красный тест
W1	Вернуть один painted footprint polygon	DOM/raster smoke и Iso golden
W2	Удалить footprint из wall collision	near-wall/nudge unit
W3	Удалить footprint из fit bounds	long-room-label fit smoke
W4	Удалить 44 px target вместе с plate	coarse-pointer smoke
W5	Вернуть fill: Canvas plate в forced colors	forced-colors contract/smoke
W6	Оставить orphan overlay texture pattern	definition-count contract

Каждый witness запускается на минимальном тесте и полностью откатывается до финального зелёного состояния.

16. Ожидаемые файлы реализации

Продукт и тесты:

• src/iso-overlays.ts;
• src/iso-scene-render.ts;
• src/styles/plan.styles.ts;
• test/iso-overlays.test.mjs;
• test/iso-scene-render.test.mjs;
• test/isometric-contract.test.mjs;
• demo/smoke_isometric_contract.mjs;
• при необходимости demo/smoke_isometric_live_touch.mjs;
• затронутые Iso golden после независимого принятия.

Документация:

• docs/ISOMETRIC.md;
• docs/ARCHITECTURE.md;
• docs/adr/160-isometric-stage3-overlays.md;
• docs/specs/160-isometric-stage3.md;
• docs/TESTING.md и docs/STATUS.md только в части действующего Stage 3 контракта/доказательств;
• этот документ и индекс docs/specs/README.md.

Backend, schema, translations и src/space-card.ts не меняются.

17. Release-артефакты

Изометрический Stage 3 остаётся скрытым за hp_alpha, поэтому по действующему решению #160 реализация имеет User-Visible: no и не получает публичную запись в docs/CHANGELOG.md, docs/CHANGELOG.ru.md, README, User Guide, HACS или release body.

Обязательны:

• синхронные manifest-driven bundles через npm run bundle:sync;
• адресные unit/contract/browser tests;
• golden:verify с ожидаемым Iso diff и отсутствием Flat diff;
• independently reviewed Linux golden acceptance;
• check-docs и штатные exact-SHA beta gates;
• обновление внутренних Stage 3 документов в том же product commit.

18. Риски и меры

Риск	Мера
Вместе с декором удаляется collision geometry	Отдельное имя footprint и exact placement unit matrix
Fit начинает клиповать длинные подписи	Footprint остаётся в scene/fit bounds; browser fit smoke
Исчезает штатная shell маркера	AC1 отдельно различает native surface и raised plate
Forced colors возвращает белые квадраты	Negative selector + forced-colors smoke
Tether/grounding исчезают из-за удаления всего subtree	Отдельные DOM assertions и golden
Golden снова закрепляет случайный фон	W1 и обязательный dense reviewed frame
Переименование внутреннего поля задевает cache	Structural fingerprint/build-count assertions
Улучшение скрытой alpha попадает в публичные notes	Явный User-Visible: no и отрицательный список артефактов

19. Откат

Кодовый откат одного product commit возвращает декоративные polygons и styles. Config/layout/store не меняются, поэтому миграция, восстановление данных и действия пользователя не нужны. Немедленный пользовательский workaround — переключиться в Flat либо отключить hp_alpha.

20. Принятые технические предположения — можно менять на ревью

1. Внутренние plate, plateHalfSize, buildIsoPlatePolygon и plateNearSilhouette переименовываются в footprint*; это снижает риск снова отрисовать safety envelope. Допустимо сохранить старые имена, если tests/docs столь же однозначно запрещают видимую поверхность.
2. renderIsoRaisedOverlays() может сохранить имя и выводить только tethers; DOM topology функции не является публичным контрактом.
3. Fit/home намеренно сохраняет прежний envelope, даже если после удаления plate визуально можно было бы вписать план плотнее. Изменение framing — другая UX-задача.
4. Opening-lock включён в единое правило, потому использует тот же общий renderer; оставшийся квадрат был бы тем же артефактом.
5. Grounding shadow остаётся допустимой непрямоугольной подсказкой связи с floor anchor и не считается заменой plate.