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

CODE-REVIEW-86-r2

• Issue: #86 — Тексты подсказок к настройкам, партия 1
• ТЗ: docs/specs/086-settings-help-content-party1.md (актуализировано 2026-08-30, зелёный SPEC-REVIEW-86-r1)
• SHA материала: 18ab3779980e1d22f2cdc4a6da12a4ef2c1a4df9 (origin/dev...HEAD, 8 коммитов: fa031920 5994c929 b4c5083f 9e559b10 be6bd5f6 4015f7f8 10f441aa 18ab3779)
• Трек: полный (нарушен критерий light-track «одна поверхность», зафиксировано автором в шапке ТЗ)
• Заход: r2 · блокирующих циклов израсходовано 1/4 (r1 — красный)

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

Между r1 (красный, материал bd27fca1→c862de65) и этим заходом ветка была перебазирована на ушедший вперёд origin/dev (комментарий автора: «ветка перебазирована на актуальный dev 8819e390»; конфликт возник в custom_components/houseplan/frontend/**, dist/**, docs/images/**, docs/CHANGELOG*.md — то есть в сгенерированных деревьях и релизных артефактах, задетых параллельно слитой #383). Предыдущие SHA (bd27fca1, 489cc8b6, c862de65, 8633187d, 3274ac39) не существуют в текущей истории (git rebase их переписал), в чём я убедился лично: git show -s <sha> на них даёт fatal: ambiguous argument. Это ровно случай PROCESS.md §2.10/§7.2 «ребейз на ушедший вперёд dev — после ребейза это другой код», поэтому разбираю AC1–AC9 заново, а не только находки r1.

Отдельно: конвейер уже один раз пытался прогнать ревью до этого рейза и остановился на конфликте («Ревью не запускалось» в issue) — тот заход не состоялся и бюджет циклов не потратил (в issue это явно записано), поэтому текущий заход законно r2, а не r3.

Скоуп

Diff добавляет 11 согласованных Party-1 hp-help-подсказок в houseplan-editor-runtime.ts (масштаб пространства, общий Glow-радиус, режим заливки, роль источника света — обновлён текст пилота #68, управление другими источниками, общий/локальный север, общий/локальный фон, стиль стен нулевой толщины, «Показывать скрытые на плане») и дублирует 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 сценарием; правит CHANGELOG×2, USER-GUIDE.ru.md, TESTING.md, docs/specs/README.md; принимает 6 golden-эталонов (+2 не связанных с #86, для уже слитой #383) и полный десятикадровый набор docs/images/** после рейза.

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

Находка r1	Чем закрыта	Где это видно
H1 (High) — docs/images/screenshots.json подделан, PNG не пересняты	Коммит 18ab3779 заменяет все 10 PNG (байты изменились) и все 10 imageSha256/sourceSha256 в манифесте, oxipng: null → "oxipng 10.2.0" — признак настоящей пересъёмки через docs:accept, а не ручной правки JSON; трейлеры Release:+Baseline-Reviewed: со ссылкой на прогон 33306281294	git show 18ab3779 --stat -- docs/images/ (11 файлов, включая JSON); я лично открыл docs/images/03-space-create.png и 06-device-editor.png — на обоих видны новые иконки-подсказки («Scale (grid cell size)» ⓘ, «Zero-thickness walls» ⓘ, «Controls other light sources» ⓘ)
H2 (High) — golden:verify красный, 6 эталонов не приняты	Коммит be6bd5f6 принимает ровно эти 6 (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) + 2 несвязанных furniture-transform-* для #383, с Release:+Baseline-Reviewed: (прогон 33305056892)	Я прогнал npm run golden:verify лично на 18ab3779 (полный лог, без truncation) — exitCode=0, все 6 сценариев passed; визуально открыл device-inbox-desktop-en-light.png, toggle-entity-dialog-desktop-en.png, space-room-color-popover-desktop-ru.png — новые ⓘ-иконки на месте, без наложений и обрезки
M1 (Medium, в скоупе) — cold-onboarding путь 5 space-подсказок не доказан исполнением	Коммит 10f441aa добавляет в smoke_help_affordance.mjs реальный запуск launchColdView() с пустым _serverCfg.spaces, дожидается _onboardingRuntime && !_editorRuntime, проверяет инвентарь всех 5 space.*.help, открытие одной подсказки, read-only черновика и то, что editor runtime не подгрузился	Я прогнал node demo/smoke_help_affordance.mjs лично — party1ColdOnboardingInventory/HelpOpens/HelpIsReadOnly/KeepsEditorLazy все true, checkAll требует true по умолчанию (падает при false), OK
L1 (Low, снят без правки) — .help-ключ не совпадает буквально с ключом label	Не задета рейзом и правками r1→r2, решение прежнее в силе	space.cell_cm.help рядом с space.scale_label, space.fill_mode.help рядом с space.fill_label — как и в r1

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

Так как разбор в этом заходе полный (см. выше — ребейз на ушедший вперёд dev), формально всё перепроверено заново на текущем SHA, а не унаследовано без проверки. Из r1 без повторной аргументации взято только:

• сам факт, что механизм hp-help/hp-dialog (#68) не форкнут и не изменён — перепроверено тем же способом (git diff по src/hp-help*, src/hp-dialog* пуст) и подтверждено заново, а не принято на слово;
• список Party-1 из 11 ключей и их каноничные RU/EN тексты — сверены заново построчно с §6 ТЗ и с тестом issue 86 Party 1 has the exact help inventory.

Никакой пункт r1 не принят по одному лишь заявлению автора без собственной проверки в этом заходе.

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

Дешёвые гейты Validate на 18ab3779 формально зелёные (прогон 33306392784), но при разборе job'ов выяснилось, что тяжёлые job'ы (Фронтенд: типы, юниты, мутанты, синхрон бандла, Golden-кадры…, Смоки в браузере…) там skipped (переиспользованы) через scripts/gate-reuse.mjs — то есть Validate НЕ прогнал их заново на этом SHA, а сверил хеш входов с прошлым успешным прогоном. Механизм легитимный (ключ = контент-хеш src/**+гарнитура job'а, не имя ветки или SHA — прочитал scripts/gate-reuse.mjs), но раз я это заметил, не полагаюсь на устную переиспользованную метку и прогнал сам:

Гейт	Команда	Результат
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	ок
3 копии бандла	cmp dist/houseplan-card.js custom_components/.../houseplan-card.js, cmp dist/houseplan-assets.json custom_components/.../houseplan-assets.json	идентичны (третья копия demo/srv/assets пересобрана тем же bundle:sync)
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	зелёный, и в этот раз обоснованно — см. закрытие H1
Выбор смоков	node scripts/smoke-select.mjs --base origin/dev --head HEAD	12 «прямое совпадение», 18 «слабая связь»
Смоки прямого совпадения (12/12)	smoke_help_affordance, 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 зелёные, включая новый cold-onboarding блок
Мутационный гейт задачи	node scripts/mutation-gate.mjs --id=settings-help-party1-placement-removed	мутант пойман
Golden	npm run golden:verify (полный лог, без tail)	exitCode=0, 0 different/missing, все 6 задетых #86 сценариев passed
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 «browser zoom 200%» не доказан ничем (Medium, в скоупе)

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

Проверил оба канала:

• grep -n "zoom" demo/smoke_help_affordance.mjs — пусто: файл проверяет только { width: 390, height: 780 } с deviceScaleFactor=1 (2-й аргумент launch), то есть узкий viewport, но никакого 200%-zoom;
• ни один из 6 принятых в рамках закрытия H2 golden-сценариев (device-inbox-*, toggle-entity-dialog-*, space-room-color-popover-desktop-ru, см. demo/golden/matrix.mjs:383-397, 765-778, 795-797) не задаёт zoom-эмуляцию; в матрице вообще нет ни одного сценария, который проверял бы party1-триггеры при 200% browser zoom (large-house-zoom-250-dark — это zoom канвы плана, а не browser-zoom диалога, и не про эту задачу).

Находка r1 упомянула эту часть AC7 мимоходом («200%-zoom и «reviewed golden» часть AC7 не доказана — см. H2»), но фактическое закрытие H2 (be6bd5f6) приняло именно и только эти 6 уже существовавших в плане сценариев — ни один из них 200%-zoom не тестирует, поэтому проблема осталась ровно там же, где была, просто перестала быть видна за красным golden:verify.

Прочитал добавленный CSS (src/styles/dialogs.styles.ts, новые .helpfieldlabel, .help-inline-label, .device-inbox-filter-help): все три класса используют display: flex/inline-flex, flex-wrap: wrap, min-width: 0 и overflow-wrap: anywhere на вложенном <label> — тот же паттерн, что и уже принятый в #68 .markerhelplabel. Это делает вероятным, что разметка действительно не обрезается при увеличении шрифта, но это чтение, а не исполнение, и для новых host-классов (.helpfieldlabel, .device-inbox-filter-help) при 200% zoom его никто — ни автор, ни предыдущий заход — не подтвердил ни автотестом, ни golden-кадром, как того явно требует собственное ТЗ задачи.

Как воспроизвести: grep -n "zoom" demo/smoke_help_affordance.mjs → 0 совпадений; grep -n "zoom" demo/golden/matrix.mjs рядом со сценариями device-inbox-*/toggle-entity-dialog-*/space-room-color-popover-desktop-ru → 0 совпадений.

Что нужно: либо добавить golden-сценарий(ы) с эмуляцией 200% zoom для одного-двух party1-диалогов (например page.emulateMedia/увеличенный fontSize/deviceScaleFactor, как принято в проекте) и smoke-проверку, что .trigger/label не выходят за visualViewport, либо явно зафиксировать в ТЗ/тестовом плане и в этом ревью, что 200%-zoom проверяется только моим чтением CSS — и указать, почему этого достаточно для приёмки. Само по себе чтение CSS без исполнения я делаю сейчас как ревьюер, но AC7 в ТЗ прямо назвал другой способ доказательства, который не выполнен.

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

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

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

• AC1 (инвентарь). grep -oE "_help\('[^']+\.help'\)" по обоим рантаймам — ровно 11 Party-1 ключей плюс существующие 8 пилотных marker.* из #68, новых мест за пределами §6 нет. 5 space.*-ключей идентичны между houseplan-editor-runtime.ts и houseplan-onboarding-runtime.ts (метод _help() в обоих файлах текстуально идентичен, src/hp-help* не менялся). Доказано тестом issue 86 Party 1 has the exact help inventory (прогнал, зелёный) и мутационным гейтом settings-help-party1-placement-removed (прогнал лично — мутант пойман).
• AC2/AC3 (канонический текст, parity). RU/EN в en.json/ru.json побайтово совпадают с таблицей §6 ТЗ — сверил вручную и тестом issue 86 Party 1 has the exact help inventory and canonical RU/EN copy (жёсткое assert.equal по каждому ключу, прогнал, зелёный). DE/FR прочитаны целиком — передают тот же смысл без пропусков предложений. .help.aria пары присутствуют во всех 4 словарях, тест i18n: every literal help call has body and full aria keys in every language зелёный (теперь явно проверяет и houseplan-onboarding-runtime.ts через объединённый helpSource, а не только cardSource, как было в r1).
• AC4 (без дублей). marker.controls_hint, gs.bg_daynight_hint, gs.north_hint, space.zero_wall_help удалены из всех 4 словарей и обоих рантаймов — тест issue 86 removes explanatory hints… зелёный, grep лично подтвердил отсутствие. Текст пилота marker.light_role.help заменён каноническим (сверил git diff — старый текст «Controls whether this marker itself is a spatial light source…» заменён на текст §6 таблицы ТЗ).
• 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) — все присутствуют в диффе шаблонов; открытие подтверждено smoke_help_affordance (party1GeneralInventory, party1SpaceInventory, party1ShowHiddenHelpIsReadOnly и т. д. — все true) и визуально — открыл device-inbox-desktop-en-light.png, toggle-entity-dialog-desktop-en.png, space-room-color-popover-desktop-ru.png, 06-device-editor.png, 03-space-create.png: везде новые ⓘ-иконки на месте своих полей, без наложений на соседние элементы и без обрезки.
• AC6 (input/a11y). Переиспользует lifecycle #68 без форка; smoke_help_affordance (прогнал, зелёный) покрывает hover/focus/click/Escape/disabled/Popover-fallback, включая keyboardFocus: true.
• AC7 (узкий viewport 390 px). Часть про 390 px доказана (party1ShowHiddenHelpInsideNarrowViewport в смоке, узкий golden device-inbox-narrow-ru-dark, toggle-entity-dialog-mobile-ru — все passed). Часть про 200% zoom — см. находку M1.
• AC8 (модель не меняется). Прочитан весь diff src/** (83+44+33 строк в трёх файлах не считая i18n) — ни одного изменения вне 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 не добавляет и не меняет ни одной пользовательской величины — только текст подсказок и разметка; правило неприменимо.
• Трейлеры и changelog. Issue: #86 на всех 8 коммитах; User-Visible: yes только на b4c5083f, в нём же правки обоих changelog; коммиты, трогающие demo/golden/baselines/** (be6bd5f6) и docs/images/** (18ab3779), несут Release:+Baseline-Reviewed: со ссылками на конкретные зелёные прогоны. docs/specs/README.md содержит строку #86 → файл спеки.
• process-gate.mjs (офлайн). Пройден, 0 предупреждений.

Вывод

Все три блокирующих находки r1 (H1, H2, M1) закрыты содержательно — я лично пересобрал бандл, прогнал golden:verify полным логом (не через tail, чтобы не потерять реальный код возврата), запустил новый cold-onboarding смок и открыл сами PNG глазами, а не поверил хендофф-комментариям. Контент-часть партии 1 (11 подсказок, 4 локали, source contract, mutation-тест) корректна и без регрессий после рейза.

Новая находка — AC7 в части «browser zoom 200%» так и не получила ни автотеста, ни golden-кадра, ни явной записи «проверено чтением» от автора, хотя ТЗ этой же задачи прямо называет это дважды (AC7 и план тестов §14). Я проверил CSS чтением и паттерн выглядит безопасным (совпадает с уже принятым в #68), но это не заменяет обещанное автором доказательство и не было названо явно нигде в хендоффе. High-находок нет, поэтому вердикт — жёлтый, а не красный: это находка уровня Medium в скоупе задачи, которая чинится в этом же issue.