houseplan-card/docs/reviews/SPEC-REVIEW-357-r1.md

SPEC-REVIEW-357-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/357
• Этап: ТЗ на ревью (PROCESS.md §2.4), лёгкий трек (small)
• Заход: r1 · блокирующих циклов израсходовано 0 из 2 (лимит для лёгкого трека — 2, §5)
• Материал: тело issue #357 (полевой отчёт + раздел «ТЗ (small-трек, S3)»), один комментарий владельца (перевод S2→S3). Кода ещё нет — ветка issue/357-* не создана (проверено: git ls-remote --heads origin не содержит её), поэтому дешёвые/тяжёлые гейты этого раунда не касаются.

Скоуп

Регрессия #337 (ленивый вынос editor-runtime): четыре тонких обёртки на HouseplanCard (_toggleIntent, _toggleStateText, _toggleConfirmationStateText, _toggleConfirmationLines) остались заглушками return this._editorRuntimeOrThrow().... — на холодной вкладке (без единого захода в редактор) _editorRuntime === null, и первый же клик по toggle-устройству в View синхронно бросает исключение до вызова HA/WS. Задача — вернуть этим четырём методам собственную реализацию на карте (то же тело, что сейчас лежит в houseplan-editor-runtime.ts:11629-11700), не трогая ничего вокруг. Соответствует SCOPE.md J3 («tap-to-toggle for safe domains») — это починка уже закрытого продуктового job, а не новая функциональность.

Small-трек заявлен корректно: сложность/риск ≤3 (механический перенос готового тела метода без изменения логики), одна поверхность (toggle-путь View-карточки), нет миграции конфига, нет нового UX-контракта (восстанавливает уже описанное в USER-GUIDE поведение тапа), нет влияния на перф/touch (данные ниже подтверждают). Ни один критерий §5 не нарушен — метка small и трек выбраны верно.

Как проверялось

Ревью ТЗ на этом этапе — не гейты, а проверка того, что диагноз и план не являются недоказанной догадкой. Прочитал код на dev (SHA 399df907, Validate зелёный) построчно вдоль каждого утверждения ТЗ:

1. Диагноз воспроизведён по коду, не только заявлен. src/houseplan-card.ts:12769-12773 — _toggleIntent карты сейчас действительно return this._editorRuntimeOrThrow()._toggleIntent(...); аналогично _toggleStateText (:12782), _toggleConfirmationStateText (:12787), _toggleConfirmationLines (:12792). _editorRuntimeOrThrow (:871-874) бросает Error('Houseplan editor runtime is not loaded'), когда _editorRuntime ещё null. _clickDevice (:5188, :5221) вызывает _toggleIntent/_toggleConfirmationLines синхронно в обработчике клика без try/catch вокруг них — исключение действительно долетает до пользователя как мёртвый клик. Диагноз подтверждён чтением, а не принят на слово.
2. Утверждение «модуль и поля уже eager» проверено, не угадано. resolveToggleIntent, formatToggleConfirmation, formatToggleIntent и компания импортированы в houseplan-card.ts статическим import { ... } from './device-toggle' (строки 131-137) — не динамическим, значит уже в initial-графе. _planHass (:4368), _fullRegistryHass (:4528), _virtualLights (:959) — существующие поля/геттеры карты. Значит перенос тела метода действительно не тянет новых зависимостей — заявление «ноль байт к initial-бюджету» технически обосновано, а не голословно.
3. Архитектурный паттерн делегирования host↔runtime не изобретён для этой задачи. interface HouseplanEditorHostPort (:805) уже существует, и в houseplan-editor-runtime.ts уже 35 мест вида return this.host._xxx(...) (например :1500, :1916, :2018) — предложенная в К1 схема «runtime-методы делегируют в host» — не новый приём, а применение существующего.
4. Все точки использования четырёх методов в View-пути перечислены полно. _clickDevice использует ровно _toggleIntent (:5188, :5231), _toggleConfirmationLines (:5221) → внутри неё _toggleConfirmationStateText → внутри неё _toggleStateText; прямой toggle без подтверждения — execute(initial) (:5241) той же цепочкой. Других методов View-путь не использует — К1 не занижает и не завышает объём переноса. _toggleIntentForDialog/_toggleHintLines (диалог маркера, редакторская поверхность) сознательно остаются заглушками на runtime — это не забытый случай, а верно исключённая часть, потому что диалог редактора не может быть открыт без загруженного runtime.
5. _tapConfirm не требует редактора. Диалог подтверждения — часть собственного рендера карты (houseplan-card.ts:11401-11415, обычный <hp-dialog> в шаблоне View), а не редакторский диалог — AC2 (tap_confirm в холодной вкладке) технически достижим без загрузки runtime.
6. Инфраструктура для AC1/AC2/AC4 существует, ссылки не придуманы. launchColdView (demo/serve.mjs:99) реально существует и уже используется для проверки «издатель runtime не запрошен по сети» в demo/smoke_lazy_editor_chunk.mjs:29-35 (тот же паттерн: слушать page.on('request'), сверять с именем файла из dist/houseplan-assets.json) — AC1(б)/AC2 не изобретают недоказанный способ проверки. scripts/smoke-links.mjs — существующий реестр (AC4 ссылается на реальный файл, не гипотетический). Файлы smoke_controls.mjs, smoke_card_controls.mjs, smoke_virtual_light_toggle.mjs, smoke_linked_virtual_light.mjs (AC3) существуют на диске; demo/smoke_ cold_view_toggle.mjs (К2) — новый, ещё не создан, что ожидаемо на этапе спецификации.
7. Продуктовая рамка. docs/SCOPE.md J3 и «lock invariant» абзац: логика resolveToggleIntent не меняется (переносится тело как есть), поэтому инвариант «замок не переключается тапом» не затрагивается переносом. docs/USER-GUIDE.ru.md (раздел про Toggle/tap_confirm) не противоречит — починка восстанавливает уже описанное поведение, нового UX-контракта нет.

Находки

Не найдено ни одной High- или Medium-находки. Диагноз проверен чтением кода и совпадает с фактическим состоянием dev; план переноса не оставляет непроверенных мест (все вызовы четырёх методов в View-пути перечислены и подтверждены); используемая тестовая инфраструктура (launchColdView, паттерн проверки сетевых запросов, smoke-links.mjs) реальна, а не гипотетична. Ни одного утверждения о поведении, которого нет в коде и не помечено как предположение, не обнаружено — диагноз и план различимы как факт, подтверждённый строкой кода, а не как догадка, выданная за решение.

Low, снятые без правки (записываю здесь по правилу §2.4):

• AC1/AC2 формально ссылаются на подпункты К2, а не формулируют собственный проверяемый текст — при беглом чтении можно спутать. Но текст К2, на который они ссылаются, однозначен и достаточен (а/б/в перечислены явно), поэтому это стилистическое, не содержательное замечание — не требует возврата.
• ТЗ не проговаривает явно, что после переноса HouseplanEditorHostPort должен получить новые члены типов для четырёх методов (упомянуто одной фразой вскользь: «порт... пополняется этими членами»). Это техническая деталь реализации, которую §7.1 явно отдаёт автору («решение записывается… либо согласовывается между собой») — не продуктовый вопрос и не повод для возврата.

Что проверено и корректно

• Диагноз регрессии — воспроизведён чтением кода построчно (не принят на слово автора).
• Технические предпосылки «перенос бесплатен» (модуль и поля eager) — подтверждены чтением импортов и полей.
• Полнота охвата: все вызовы четырёх переносимых методов в View-пути найдены и совпадают с объёмом К1 — ничего не забыто, ничего лишнего не включено.
• Архитектурный приём (host-порт, делегирование) — не новый для проекта.
• Ссылки на тестовую инфраструктуру (launchColdView, smoke_lazy_editor_chunk.mjs, smoke-links.mjs, четыре существующих смока AC3) — все существуют и делают то, что им приписано.
• Соответствие SCOPE.md (J3, lock invariant) и отсутствие противоречия с USER-GUIDE.ru.md — рамка выдержана.
• Small-трек: все пять критериев §5 выполнены одновременно, нарушенных нет.
• Откат («один revert, публичные контракты и конфиг не меняются») — реалистичен для механического переноса тела метода.

Чего не проверял

• Гейты typecheck/test/build/golden/смоки — не прогонял: кода ещё нет, ветка issue/357-* не существует. Это гейты код-ревью (§2.7), не ревью ТЗ.
• Не оценивал производительность фактическим замером (bundle:budget) — на этом этапе оцениваю только правдоподобность заявления «ноль байт к initial-графу» по факту уже-eager зависимостей; фактическую цифру проверит код-ревью после того, как появится диф.
• Не проверял качество будущего demo/smoke_cold_view_toggle.mjs — файла ещё нет, это предмет код-ревью.

Вердикт

Зелёный. AC1…AC5 однозначны, у каждого назван способ доказательства (browser-smoke, конкретные файлы), диагноз подтверждён чтением кода, а не принят на веру, план переноса покрывает весь фактический объём использования (не больше и не меньше). Открытых продуктовых вопросов нет — задача мала и решать в ней действительно нечего сверх уже описанного в USER-GUIDE поведения. Готово к разработке.