houseplan-card/docs/reviews/CODE-REVIEW-86-r3.md

CODE-REVIEW-86-r3

• Issue: #86 — Тексты подсказок к настройкам, партия 1
• ТЗ: docs/specs/086-settings-help-content-party1.md (актуализировано 2026-08-30, зелёный SPEC-REVIEW-86-r1)
• SHA материала: 96bd3e3eccaaa57fae8a46159b90eb0702e2066b (origin/dev...HEAD, 10 коммитов: 009f784d 82585520 30df567d d2d70df5 ffd61def 85e0f09f dbfaf48b 414933e2 0fc9b985 96bd3e3e)
• Трек: полный (нарушен критерий light-track «одна поверхность», зафиксировано автором в шапке ТЗ)
• Заход: r3 · блокирующих циклов израсходовано 2/4 (r1 — красный, r2 — жёлтый)

Почему разбор полный, а не по дельте

Конвейер привёл ветку к dev до этого ревью: поверх материала r2 (18ab3779) легли новые коммиты origin/dev (branch base сдвинулась с прежней 8819e390/ba568763 на текущую d14cf769, тип #44). Это переписало все SHA веткb — я лично проверил: все восемь SHA, перечисленных в шапке CODE-REVIEW-86-r2.md (fa031920, 5994c929, b4c5083f, 9e559b10, be6bd5f6, 4015f7f8, 10f441aa, 18ab3779), дают fatal: Not a valid object name в текущей истории (git cat-file -e <sha> на каждом). Это ровно случай PROCESS.md §2.10/§7.2 «ребейз на ушедший вперёд dev — после ребейза это другой код», поэтому разбираю AC1–AC9 заново на 96bd3e3e, а не только находку r2.

Я сопоставил новые SHA со старыми по содержимому коммитов (сообщение + диф), чтобы не потерять картину: 009f784d→(было fa031920, спека), 82585520→(5994c929, актуализация спеки), 30df567d→(b4c5083f, feat), d2d70df5→(9e559b10, no-new-any), ffd61def→(be6bd5f6, golden accept, закрытие H2), 85e0f09f→(4015f7f8, docs review r1), dbfaf48b→(10f441aa, cold-onboarding smoke, закрытие M1-r1), 414933e2→(18ab3779, docs accept, закрытие H1), затем новый коммит r2-документа 0fc9b985, и поверх — новый для r3 коммит 96bd3e3e (200%-zoom smoke, попытка закрытия M1-r2). Содержимое каждой пары (кроме родителя) идентично по git show <new> -- <path>, проверил построчно на трёх крупнейших (30df567d, ffd61def, 414933e2).

Скоуп

Diff (origin/dev...HEAD за вычетом сгенерированных dist/**, custom_components/**/frontend/**) добавляет 11 согласованных Party-1 hp-help-подсказок в houseplan-editor-runtime.ts и дублирует 5 space-подсказок в houseplan-onboarding-runtime.ts; переводит их на en/ru/de/fr; удаляет 4 старых .rhint; добавляет unit-тесты инвентаря/parity/no-duplicate, мутационный тест settings-help-party1-placement-removed, расширяет smoke_help_affordance.mjs cold-onboarding и 200%-browser-zoom сценариями; правит CHANGELOG×2, USER-GUIDE.ru.md, TESTING.md, docs/specs/README.md; принимает 6 golden-эталонов party1 (+2 не связанных с #86, для уже слитой #383) и полный десятикадровый набор docs/images/** после рейза; несёт два собственных документа ревью (docs/reviews/CODE-REVIEW-86-r1.md, -r2.md) как часть истории ветки.

Единственная содержательная новая работа с момента r2 — коммит 96bd3e3e (browser-zoom smoke); всё остальное — тот же контент, что и в r2, просто с новыми SHA после рейза.

Закрытие раунда r2

Находка r2	Чем закрыта	Где это видно
M1 (Medium, в скоупе) — AC7 «browser zoom 200%» не доказан ничем: ни автотестом, ни golden-кадром, хотя ТЗ §13/§14 требует оба канала	Частично. Коммит 96bd3e3e добавляет в demo/smoke_help_affordance.mjs реальный browser-смок: launch({width:390,height:900}, 2) — тот самый renderer-контракт «780 физических px → 390 CSS px при DPR 2», который сама ТЗ §14 описывает как метод; открывает gs.bg_mode.help, проверяет 5 фактов (zoomApplied, triggerInside, tooltipInside, noHorizontalDialogOverflow, stageStable). Я прогнал node demo/smoke_help_affordance.mjs лично — все пять party1BrowserZoom200* = true, тест не тавтологичен: inside() зависит от реального getBoundingClientRect(), при отсутствии триггера/тултипа вернул бы false. Golden-часть не закрыта: git diff origin/dev...HEAD -- demo/golden/matrix.mjs — пусто, никакой 200%-zoom/deviceScaleFactor-сценарий для party1-диалогов не добавлен ни в r2, ни в r3. См. новую находку M1 ниже — это тот же пробел ТЗ, наполовину закрытый.

Унаследовано из r2

Формально разбор в этом заходе полный (см. выше), поэтому ничего не принято только на основании прежнего документа без собственной проверки на 96bd3e3e. Из r2 без повторной аргументации, но с повторной проверкой факта, взято:

• механизм hp-help/hp-dialog (#68) не форкнут — перепроверено (git diff origin/dev...HEAD по src/hp-help*, src/hp-dialog* пуст) на текущем SHA, а не принято на слово из CODE-REVIEW-86-r2.md;
• список Party-1 из 11 ключей и их каноничные RU/EN тексты — сверены заново построчно с §6 ТЗ и с тестом issue 86 Party 1 has the exact help inventory на 96bd3e3e, прогнан лично;
• содержимое docs/images/** — открыл 06-device-editor.png и 03-space-create.png заново глазами на текущем SHA (не переиспользовал скриншот из r2-документа): оба показывают новые ⓘ-иконки («Controls other light sources», «Is this device a light source?», «Scale (grid cell size)», «Zero-thickness walls»). check-docs.mjs зелёный на 96bd3e3e.

Находка L1 (низкая, снята без правки в r1/r2 — .help-ключ не совпадает буквально с ключом label) не задета ни рейзом, ни новым коммитом; решение прежних раундов остаётся в силе, повторно не аргументирую.

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

Зелёного Validate на 96bd3e3e на момент ревью не найдено — прогнал дешёвые и целевые гейты лично:

Гейт	Команда	Результат
Typecheck	npx tsc --noEmit	зелёный
Unit	npm test	1611 тестов, 1610 pass, 1 skip (тот же приватный #281-фикстур-скип, что и на origin/dev, к #86 не относится), 0 fail
Build + sync	npm run build, npm run bundle:sync	ок, git status после — чисто (три копии бандла уже были синхронны)
3 копии бандла	cmp dist/houseplan-card.js custom_components/.../houseplan-card.js, cmp dist/houseplan-assets.json custom_components/.../houseplan-assets.json, cmp dist/houseplan-card.js demo/srv/assets/houseplan-card.js	идентичны (все три)
Bundle budget	npm run bundle:budget	initial View 280 304 B гзип, бюджет 300 000 — в норме
no-new-any	node scripts/no-new-any.mjs --base origin/dev --head HEAD	119 добавленных строк в 3 файлах, новых any нет
check-docs	node scripts/check-docs.mjs	зелёный (7 файлов, 10 внешних ссылок); визуально перепроверил 2 из 10 кадров лично (см. «Унаследовано»)
Выбор смоков	node scripts/smoke-select.mjs --base origin/dev --head HEAD	12 «прямое совпадение», 18 «слабая связь» — тот же список, что и в r2 (diff содержательно не изменился, кроме теста)
Смоки прямого совпадения (12/12)	smoke_help_affordance (включая новый cold-onboarding и 200%-zoom блоки), smoke_bg_color, smoke_color_picker_consumers, smoke_device_inbox, smoke_dialog_zombie, smoke_disabled_device, smoke_esc_dialogs, smoke_gs_always, smoke_ha_controls, smoke_hidden_flag, smoke_motion_sense, smoke_sun	все 12 зелёные
Мутационный гейт задачи	node scripts/mutation-gate.mjs --id=settings-help-party1-placement-removed	поймано 1 из 1, гейт-чек (npx tsc -p tsconfig.test.json && node scripts/fix-test-build.mjs && node --test ...) сам по себе чистый
Golden	npm run golden:verify (полный лог, без tail, второй прогон отфильтрован grep на именованные сценарии)	exitCode=0; явно проверил, что все 8 связанных с #86/#383 сценариев (device-inbox-desktop-en-light, device-inbox-desktop-ru-dark, device-inbox-narrow-ru-dark, toggle-entity-dialog-desktop-en, toggle-entity-dialog-mobile-ru, space-room-color-popover-desktop-ru, furniture-transform-light, furniture-transform-dark) — все passed; ни одного different/missing во всём прогоне
DE/FR полный перевод	ручное чтение всех 11 .help + .aria в de.json/fr.json	смысл передан полностью, пропусков предложений нет
process-gate (офлайн)	node scripts/process-gate.mjs	пройден, 0 предупреждений (проверка статуса issue пропущена — нет --issues)

Что не прогонял и почему:

• 18 «слабых связей» из smoke-select (общее имя _config) — все про геометрию/локали/optimize, diff их логики не касается, сигнала для расширения после 12/12 прямых совпадений нет;
• python -m pytest tests_backend -q — diff не касается custom_components/**/*.py (только сгенерированные фронтенд-бандлы внутри);
• остальные ~193 браузерных смока и performance_smoke — задача не задевает геометрию/перф-чувствительные пути, полный прогон здесь избыточен (§8: полные наборы — предрелизный гейт);
• model-invariants — diff не трогает геометрию, ссылки, layout, marker.space, open_spans; неприменимо.

Находки

M1 — AC7 «представительный reviewed golden» для browser zoom 200% так и не появился (Medium, в скоупе)

ТЗ формулирует AC7 как двухканальное доказательство: «Узкий viewport 390 px и browser zoom 200% не обрезают tooltip/trigger и не меняют stage geometry. Доказательство: smoke + representative reviewed golden» (§13), а план автотестов (§14) отдельно и явно перечисляет golden-требование: «Golden: … light/dark and 200% zoom; full Linux artifact review required» — отдельной строкой от смок-плана про тот же 200%-zoom layout-pass.

r2 закрыл ровно половину: 96bd3e3e добавил рабочий смок (проверил лично, см. таблицу выше и «Закрытие раунда r2»). Golden-половина не появилась ни в r2, ни в этом коммите:

• git diff origin/dev...HEAD -- demo/golden/matrix.mjs — пусто, ни один сценарий не добавлен и не изменён этим diff'ом вообще;
• grep -n "zoom\|deviceScaleFactor\|dpr2" demo/golden/matrix.mjs — единственное совпадение dpr2: true относится к неродственному сценарию tunnelContinuity (геометрия проёмов, строка 484), а large-house-zoom-* (строки 130–131, 743–746) — это zoom канвы плана (zoom: 0.4/2.5), а не browser-zoom диалога, и не про #86 (уже отмечено ещё в r2);
• ни один из 8 принятых по #86/#383 golden-кадров (см. таблицу «Как проверялось») не задаёт deviceScaleFactor/увеличенный fontSize — все они сняты при обычном масштабе.

Это тот же пробел ТЗ, что и M1 из r2, просто теперь наполовину закрыт: сам факт «trigger/tooltip не обрезаются при 200% zoom» теперь доказан исполнением (смок), но собственное требование ТЗ о golden-кадре с человеческим ревью реального рендера при 200% zoom остаётся неисполненным после двух раундов внимания именно к этому AC. Я не могу заменить это решение своим чтением CSS или доверием к смоку: ТЗ называет golden отдельным обязательным каналом доказательства, а не альтернативой смоку, и это продуктовое решение автора ТЗ (какая степень доказательства нужна для рендер-регрессий), а не техническая деталь реализации, которую покрывает свобода §7.1.

Как воспроизвести: git diff origin/dev...HEAD -- demo/golden/matrix.mjs → пустой diff; grep -n "zoom\|deviceScaleFactor" demo/golden/matrix.mjs → только неродственные совпадения.

Что нужно: добавить в demo/golden/matrix.mjs минимум один representative party1-сценарий (например тот же gs.bg_mode.help в общих настройках или один space-диалог) с deviceScaleFactor: 2 и уменьшенным viewport.width (390 CSS px, как в смоке) для light и dark тем — как прямо требует §14 — принять через npm run golden:accept -- --reviewed на полном Linux-артефакте, приложить ссылку на прогон. Альтернатива — явно зафиксировать в ТЗ (правкой документа, не просто в хендоффе) решение владельца/автора о том, что golden-канал для этого под-AC избыточен и смока достаточно, с обоснованием; тогда это перестанет быть находкой. Пока такой записи нет ни в ТЗ, ни в решениях владельца по #86, действующий контракт — тот, что в §13/§14.

L1 — .help-ключ не совпадает буквально с ключом видимого label (Low, снимается без правки)

Унаследовано из ревью ТЗ (SPEC-REVIEW-86-r1) и CODE-REVIEW-86-r1/r2: space.cell_cm.help соседствует с space.scale_label, space.fill_mode.help — с space.fill_label. Не создаёт двусмысленности контракта, тот же паттерн уже был у пилотов #68, находится в рамках технической свободы реализации по PROCESS.md §7.1. Не задето ни рейзом, ни коммитом 96bd3e3e. Оставляю без правки.

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

• AC1 (инвентарь). grep -oE "_help\('[^']+\.help'\)" по обоим рантаймам на 96bd3e3e — ровно 11 Party-1 ключей плюс существующие 8 пилотных marker.* из #68, новых мест за пределами §6 нет. 5 space.*-ключей идентичны между houseplan-editor-runtime.ts и houseplan-onboarding-runtime.ts. Доказано тестом issue 86 Party 1 has the exact help inventory (прогнал, зелёный) и мутационным гейтом settings-help-party1-placement-removed (прогнал лично — мутант пойман).
• AC2/AC3 (канонический текст, parity). RU/EN в en.json/ru.json побайтово совпадают с таблицей §6 ТЗ — сверил тестом (жёсткий assert.equal, прогнал, зелёный). DE/FR прочитаны целиком лично — передают тот же смысл без пропусков предложений. .help.aria пары присутствуют во всех 4 словарях, тест i18n: every literal help call has body and full aria keys in every language зелёный (проверяет объединённый helpSource — оба рантайма).
• AC4 (без дублей). marker.controls_hint, gs.bg_daynight_hint, gs.north_hint, space.zero_wall_help удалены из всех 4 словарей и обоих рантаймов — тест issue 86 removes explanatory hints… зелёный, grep лично подтвердил отсутствие.
• AC5 (все поверхности). General (gs.glow_radius, gs.bg_mode, gs.north), Space (space.cell_cm, space.zero_wall_style, space.bg_mode, space.north, space.fill_mode), Marker (marker.controls.help) и Device catalog (device_inbox.show_hidden.help) — все присутствуют в diff'е шаблонов; открытие подтверждено smoke_help_affordance (все party1*Inventory флаги true) и визуально — открыл 06-device-editor.png, 03-space-create.png, а через golden:verify подтвердил ещё 6 кадров (device-inbox-*, toggle-entity-dialog-*, space-room-color-popover-desktop-ru) без наложений/обрезки.
• AC6 (input/a11y). Переиспользует lifecycle #68 без форка; smoke_help_affordance (прогнал, зелёный) покрывает hover/focus/click/Escape/disabled/Popover-fallback, включая keyboardFocus: true.
• AC7 (узкий viewport 390 px + 200% zoom). Часть про 390 px доказана и смоком (party1ShowHiddenHelpInsideNarrowViewport), и golden (device-inbox-narrow-ru-dark, toggle-entity-dialog-mobile-ru, оба passed). Часть про 200% zoom теперь доказана смоком (party1BrowserZoom200*, все 5 флагов true, прогнал лично), но не golden-каналом — см. находку M1.
• AC8 (модель не меняется). Прочитан весь diff src/** — ни одного изменения вне JSX-шаблонов, CSS и _help()-геттеров; strictNumber, touchSpaceDisplay, @change/@input обработчики не тронуты. npm test (1610/1611 pass) включает существующие config-serialization снапшоты — без регрессий.
• AC9 (партии 2/3 отсутствуют). src/** вне i18n просмотрен построчно — только houseplan-editor-runtime.ts, houseplan-onboarding-runtime.ts, dialogs.styles.ts; ни одного _help() вне §6 сверх уже существующих пилотов; в i18n нет ключей opening.*/wallthick.*/decor.*/device.binding.* партий 2/3.
• Одно число — один источник. Diff не добавляет и не меняет ни одной пользовательской величины — только текст подсказок и разметка; правило неприменимо. test/single-source-numbers.test.mjs прошёл в составе npm test.
• Трейлеры и changelog. Issue: #86 на всех 10 коммитах; User-Visible: yes только на 30df567d, в нём же правки обоих changelog (проверил git show 30df567d -- docs/CHANGELOG.md docs/CHANGELOG.ru.md). Коммиты, трогающие demo/golden/baselines/** (ffd61def) и docs/images/** (414933e2), несут Release:+Baseline-Reviewed: со ссылками на зелёные прогоны. docs/specs/README.md содержит строку #86 → файл спеки.
• process-gate.mjs (офлайн). Пройден, 0 предупреждений.

Вывод

Контент-часть партии 1 (11 подсказок, 4 локали, source contract, mutation-тест, cold-onboarding поведение) корректна и без регрессий после второго рейза — я лично пересобрал бандл, прогнал golden:verify полным логом, все 12 прямых смоков и заново открыл документационные кадры, а не принял их на слово из документа r2.

Новый коммит 96bd3e3e реально закрывает исполняемую часть находки r2 (M1): поведение при 200% browser zoom теперь доказано смоком, который умеет падать. Но собственное требование ТЗ §13/§14 о golden-кадре для этого же under-AC — отдельный, явно названный канал доказательства — так и не выполнено ни в r2, ни здесь. High-находок нет, поэтому вердикт снова жёлтый, а не красный: то же самое требование ТЗ, что и в r2, теперь закрыто наполовину вместо нуля, и чинится в этом же issue без нового цикла спецификации.