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

SPEC-REVIEW #400 · заход r1

• Issue: https://github.com/Matysh/houseplan-card/issues/400
• Артефакт ТЗ: docs/specs/400-beta-polish.md
• SHA материала: 60c211c82ad12940e68040de1455f13a1410683e (HEAD ветки issue/400-beta-polish, единственный коммит docs: specify the beta polish batch (#400))
• Трек: полный (три несвязанные поверхности — рендер .dtframe, состав ленивых чанков, _alignCandidates); критерий small «одна поверхность» явно назван как нарушенный в шапке ТЗ. Заход r1, лимит цикла 4 (полный трек).

Скоуп

ТЗ объединяет три пункта из аудита беты v1.70.0-beta.1 (прецеденты #369, #385 подтверждают практику батчить несколько Low/Medium-находок аудита в одно ТЗ):

1. M5 — осевые ручки трансформ-рамки декора (.dtframe) рисуются поверх угловых и на мелкой мебели (≲80 см) забирают часть хит-зоны угла.
2. Low «б» — 38 ключей помощи en/ru лежат в initial-чанке, а не в ленивом чанке редактора.
3. Low «г» — исключение перетаскиваемого маркера в _alignCandidates (режим devices) опирается на мёртвый this.host._drag?.id вместо _deviceDrag?.id.

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

Ревью ТЗ — не код-ревью: продуктовый код не менялся, гейты (typecheck, test, build) неприменимы на этом этапе и не запускались. Проверка велась чтением исходников на SHA выше и сверкой с ТЗ.

Проверено построчно:

• src/houseplan-card.ts:8439 — hr = Math.max(view.w, view.h) * 0.018, общий для угловых (:8467, corners.map) и осевых (:8474, sides.map) ручек. sides.map рендерится после corners.map в одном шаблоне → на overlap-зоне хит достаётся последним отрисованным (осевым) кругам. Комментарий кода на месте (:8434-8438) подтверждает решение владельца от 2026-08-05 «уменьшить в 4 раза» — оно относится к видимой бусине kr = hr/4, не к хит-радиусу hr; ТЗ корректно исключает hr из скоупа.
• src/houseplan-editor-runtime.ts:10943,10970 — метод называется _alignCandidates() (ТЗ ссылается на него верно); в ветке devices исключение действительно идёт по this.host._drag?.id (:10970). _drag (houseplan-card.ts:2547) и _deviceDrag (:2548, заполняется :6736) — разные поля; в режиме devices перетаскивание всегда через _deviceDrag, _drag там не присваивается — подтверждает «мёртвый источник».
• demo/smoke_align_guides.mjs (ветка «редактор устройств», строки 30-47) — прочитан целиком. Сценарий 3 подтверждает диагноз ТЗ буквально: _layout[b] выставляется на ту же Y, что и цель выравнивания, _deviceDrag включается для b, и guides() >= 1 не различает «гид от a» и «гид от самого b», потому что кандидат b (не исключённый живым _drag=null) физически совпадает с целью. Смок не умеет упасть на этот дефект — ТЗ прав, что нужна правка теста (AC5), а не только кода.
• src/logic.ts:1977 — alignGuides(pt, candidates, tol) существует и принимает список кандидатов, как описано.
• dist/houseplan-assets/houseplan-card-*.js — grep -c '\.help\.' находит совпадение только в initial-чанке (houseplan-card-*.js), не в editor-*.js; de-*.js/fr-*.js существуют как отдельные lazy-чанки (src/i18n/de.ts, src/i18n/fr.ts помечены «lazy» в комментариях) — ровно та архитектура, которую описывает ТЗ («en/ru всегда в initial, лениво только de/fr»).
• scripts/bundle-budget.mjs:34 — INITIAL_VIEW_GZIP_BUDGET = 300_000 — совпадает с числом в ТЗ (примечание: AGENTS.md в другом месте называет устаревшее «256000 B» из #337 — расхождение самого AGENTS.md с текущим кодом, не дефект этого ТЗ).
• Сверены все внешние ссылки: issue #383 (мебель resize, closed), #369/#385 (прецеденты батч-ТЗ), #352/#355 (архитектура ленивых словарей), #337 (ленивый editor-чанк), #74 (undo/redo устройств, откуда возникло состояние _deviceDrag) — все существуют и релевантны заявленному контексту.
• docs/FURNITURE.md, docs/DECOR-EDITOR.md, docs/USER-GUIDE.ru.md (строка 1293) — описывают поведение угловых/средних ручек мебели в общих словах, ни один не фиксирует приоритет хита при пересечении кругов. Правка AC1 не противоречит ни одному канону, новый контракт не заменяет и не ломает задокументированное поведение.
• docs/TOUCH-SUPPORT.md — редактор подложки (декор) отнесён к «best-effort»-поверхностям; правка — только хит-приоритет уже существующей десктоп-ручки, нового touch-контракта не создаёт.
• scripts/mutation-gate.mjs — существующие id мутантов оформлены как kebab-case-описание дефекта; два новых id из ТЗ (furniture-edge-handles- steal-the-corner, align-guides-exclude-dead-source) следуют тому же стилю.

Находки

Ни одной находки High или Medium. Две Low, обе сняты ревьюером с записью (не требуют возврата автору):

• Low. Раздел «Release-артефакты» не проговаривает пункт docs/specs/README.md «затронутая пользовательская документация» явно (в отличие от i18n/модели данных, где ТЗ пишет «не применимо»). По факту docs/USER-GUIDE.ru.md:1293 уже описывает угловой/осевой resize мебели в терминах, которые AC1 не меняет (контракт «углы двигаются плавно и по умолчанию сохраняют пропорции» остаётся верным, меняется только надёжность попадания) — обновление не требуется по существу. Снято: добавление пустой строки «USER-GUIDE не меняется» ничего не изменило бы в приёмке.
• Low. ТЗ не проговаривает влияние на touch явно (пункт DoR §2.5), хотя явно проговаривает i18n и модель данных. Поверхность — редактор подложки, который весь целиком best-effort на touch (docs/TOUCH-SUPPORT.md), а правка — приоритет хита у уже существующей десктоп-ручки без изменения touch-контракта. Снято: добавлять строку «touch: без изменений» формально корректно, но не несёт информации сверх уже действующей политики.

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

• Оба обязательных продуктовых раздела на месте: персона/поверхность/момент (Сценарий) и «что человек увидит» одной фразой на каждый из трёх пунктов — включая честное «видимой разницы нет» для пунктов (2) и (3).
• Трек выбран верно и обоснован явным нарушенным критерием («одна поверхность»), а не общей отговоркой — соответствует правилу AGENTS.md после #338.
• Все три технических контракта проверяемы и не оставляют скрытых допущений, выданных за факт: формулировка M5 из исходного аудита («ресайз углом недоступен») explicitly исправлена на подтверждённую замером и явно более слабую («зона урезана вдвое»), с указанием, что именно осталось непроверено (elementFromPoint через shadow root) и почему выбран другой способ доказательства (синтетический pointerdown вместо elementFromPoint).
• Технические решения, не видимые пользователю (два исхода по help-чанку, порядок отрисовки vs скрытие осевых ручек, имена тестовых файлов и мутантов), явно поданы как варианты с обоснованным дефолтом и оставлены реализации — ровно то, что требует §7.1, без скрытых догадок, выданных за решение.
• AC1…AC6 пронумерованы, у каждого указан способ доказательства (smoke/unit/gate-команда/код-ревью), и план автотестов покрывает AC1, AC2, AC4, AC5 конкретными тестовыми сценариями; AC3 и AC6 — gate-командами (grep+замер бюджета, npm run bundle:budget), что допустимо по DoR §2.5.
• Мутанты в плане нацелены именно на регрессии, которые новый тест должен ловить (возврат старого порядка отрисовки → красный AC1; возврат _drag?.id → красные AC4/AC5) — дисциплина «тест умеет падать» заложена в сам план, а не декларирована.
• Скоуп/не-скоуп корректно исключает смежные, но чужие задачи: hr (владелец, 2026-08-05), механику ресайза мебели (#383), тексты помощи (#86), архитектуру ленивой поставки словарей (#352–#355) — предотвращает расползание батча.
• Откат прост и не трогает пользовательские данные (два блока шаблона, состав чанка/строка документации, одно поле условия).
• Ссылки issue ↔ ТЗ на месте в обе стороны (шапка ТЗ → issue; в issue есть единственный комментарий S2-анализа, который ведёт к тому же батчу).

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

• Не запускал typecheck/test/build/bundle:budget — на этапе ревью ТЗ продуктовый код не менялся, гейты неприменимы; они станут предметом код-ревью.
• Не проверял браузером фактическое перекрытие ручек в px (14 px, порог «≈80 см») — принято как измерение автора в реальном DOM, зафиксированное в комментарии S2-анализа; для этапа спек-ревью это описание проблемы, а не критерий приёмки (критерий приёмки — бинарный AC1/AC2, он проверяем независимо от точной пороговой цифры).
• Не проверял точное текущее значение запаса бюджета (15 945 Б) и суточный расход (6,1 КБ) — это мотивационный фон проблемы (2), не предмет AC; AC3/AC6 сформулированы как проверяемые независимо от этих чисел.
• Не оценивал техническую реализуемость исхода (1) для пункта (2) (вынос help-ключей без второго сетевого запроса) — ТЗ прямо оставляет это реализации с честным запасным исходом (2), что и требуется от технического решения на этом этапе.

Вердикт

Зелёный. ТЗ полное по §7.1, критерии проверяемы, трек обоснован, ссылки и факты в тексте подтверждены чтением кода на SHA 60c211c8. Обе Low-находки сняты ревьюером с записью выше — доработки не требуют.