docs: review document for #266

Issue: #266
User-Visible: no

docs/images/screenshots.json

@@ -2,7 +2,7 @@
   "version": 1,
   "fixture": "synthetic-only",
   "chromium": "151.0.7922.34",
-  "sourceFingerprint": "da2136b0e110b8b4173c465625648cc368e54c34b33cf17bb2ded0cc82c36b2e",
+  "sourceFingerprint": "49a41e2ee61a9767b42b400defc7e45d0ec5fa64f6c3c832fe4b5a8a7d560601",
   "captureScriptSha256": "ce2e9542fed9dade3085be87d16f69adb2ac8262893ad78ad966b1b9673f2983",
   "command": "npm run build && node demo/docs/capture.mjs",
   "scenarios": {
@@ -14,7 +14,7 @@
       },
       "theme": "dark",
       "language": "en",
-      "sourceSha256": "da2136b0e110b8b4173c465625648cc368e54c34b33cf17bb2ded0cc82c36b2e",
+      "sourceSha256": "49a41e2ee61a9767b42b400defc7e45d0ec5fa64f6c3c832fe4b5a8a7d560601",
       "imageSha256": "0ca982495a7749907c48ebbddfd089c54385a4347f79f64e94af2c5a8d5c03eb"
     },
     "view-touch": {
@@ -25,7 +25,7 @@
       },
       "theme": "dark",
       "language": "en",
-      "sourceSha256": "da2136b0e110b8b4173c465625648cc368e54c34b33cf17bb2ded0cc82c36b2e",
+      "sourceSha256": "49a41e2ee61a9767b42b400defc7e45d0ec5fa64f6c3c832fe4b5a8a7d560601",
       "imageSha256": "1c8e28ff34736b936ba7c9ec047d1da27aaf6fbb01411155f2d5c05282c02c41"
     },
     "space-create": {
@@ -36,7 +36,7 @@
       },
       "theme": "dark",
       "language": "en",
-      "sourceSha256": "da2136b0e110b8b4173c465625648cc368e54c34b33cf17bb2ded0cc82c36b2e",
+      "sourceSha256": "49a41e2ee61a9767b42b400defc7e45d0ec5fa64f6c3c832fe4b5a8a7d560601",
       "imageSha256": "329750c81a7a958c4fd105b2c80f85dce55ed87df9ddf0ea08084e4428e85f04"
     },
     "room-contour-close": {
@@ -47,7 +47,7 @@
       },
       "theme": "dark",
       "language": "en",
-      "sourceSha256": "da2136b0e110b8b4173c465625648cc368e54c34b33cf17bb2ded0cc82c36b2e",
+      "sourceSha256": "49a41e2ee61a9767b42b400defc7e45d0ec5fa64f6c3c832fe4b5a8a7d560601",
       "imageSha256": "ff2e903e548423aa0aa52680e20b8ad951c704e01130cb4b180222015a241276"
     },
     "plan-context-tray": {
@@ -58,7 +58,7 @@
       },
       "theme": "dark",
       "language": "en",
-      "sourceSha256": "da2136b0e110b8b4173c465625648cc368e54c34b33cf17bb2ded0cc82c36b2e",
+      "sourceSha256": "49a41e2ee61a9767b42b400defc7e45d0ec5fa64f6c3c832fe4b5a8a7d560601",
       "imageSha256": "ff55925f079411023442e7e7dd5ed528c331aaa3fd3fc2fbbf3b1aaf34a85718"
     },
     "device-editor": {
@@ -69,7 +69,7 @@
       },
       "theme": "dark",
       "language": "en",
-      "sourceSha256": "da2136b0e110b8b4173c465625648cc368e54c34b33cf17bb2ded0cc82c36b2e",
+      "sourceSha256": "49a41e2ee61a9767b42b400defc7e45d0ec5fa64f6c3c832fe4b5a8a7d560601",
       "imageSha256": "6b9cd281450e7782cff292f11efc58d227bedd0df86afc3be987feb2edec9dc3"
     },
     "device-display-preview": {
@@ -80,7 +80,7 @@
       },
       "theme": "dark",
       "language": "en",
-      "sourceSha256": "da2136b0e110b8b4173c465625648cc368e54c34b33cf17bb2ded0cc82c36b2e",
+      "sourceSha256": "49a41e2ee61a9767b42b400defc7e45d0ec5fa64f6c3c832fe4b5a8a7d560601",
       "imageSha256": "6f628abe6b89d7c4b352e6d73ac0b126526f6fdba5927bb774c5b884e484ca19"
     },
     "background-editor": {
@@ -91,7 +91,7 @@
       },
       "theme": "dark",
       "language": "en",
-      "sourceSha256": "da2136b0e110b8b4173c465625648cc368e54c34b33cf17bb2ded0cc82c36b2e",
+      "sourceSha256": "49a41e2ee61a9767b42b400defc7e45d0ec5fa64f6c3c832fe4b5a8a7d560601",
       "imageSha256": "a1d1a905f1410f73231d2ea5d1dfbd8ae79c2fe8b0a79cff87ebb977ac7a3103"
     },
     "room-card": {
@@ -102,7 +102,7 @@
       },
       "theme": "dark",
       "language": "en",
-      "sourceSha256": "da2136b0e110b8b4173c465625648cc368e54c34b33cf17bb2ded0cc82c36b2e",
+      "sourceSha256": "49a41e2ee61a9767b42b400defc7e45d0ec5fa64f6c3c832fe4b5a8a7d560601",
       "imageSha256": "48a5685039a5e0de2a28190d857b193c86e2e63606e3c7a8c40fc9d2b190da4e"
     },
     "device-info": {
@@ -113,7 +113,7 @@
       },
       "theme": "dark",
       "language": "en",
-      "sourceSha256": "da2136b0e110b8b4173c465625648cc368e54c34b33cf17bb2ded0cc82c36b2e",
+      "sourceSha256": "49a41e2ee61a9767b42b400defc7e45d0ec5fa64f6c3c832fe4b5a8a7d560601",
       "imageSha256": "29a342811aaedaebc54ba337792d60cb454a7cf4c3063b210f6c4bafe0a4d87b"
     }
   }

docs/reviews/CODE-REVIEW-266-r2.md

@@ -0,0 +1,103 @@
+# CODE-REVIEW-266-r2
+
+Issue: #266 — «Рефакторинг 3/5: расщепить styles.ts — 3 648 строк в одном шаблоне css``»
+Этап: code (PROCESS.md §2.7). Заход: r2 · блокирующих циклов израсходовано 0 из 4 (r1 был зелёным и цикла не образовал, #227).
+Материал: `git log --oneline origin/dev..HEAD`, `git diff origin/dev...HEAD` на SHA `7fd0ae4b` (HEAD detached, ветка `origin/issue/266-split-styles`).
+ТЗ: `docs/specs/266-split-styles.md`, ревизия 3 (SPEC-REVIEW-266-r3 — зелёный, High 0 / Medium 0).
+Предыдущий раунд: CODE-REVIEW-266-r1 (зелёный, High 0 / Medium 0), вердикт-комментарий не называл SHA — по инструкции разбора это само по себе находка; см. раздел «Аудит r1» ниже, где отсутствие SHA оказалось не формальностью, а маркером реальной проблемы.
+
+## 0. Важное замечание о состоянии `dev`
+
+`origin/dev` уже указывает на `fd4bf0e9` — код #266 смерджен (метка `S8-merged`), и на нём стоит `docs/reviews/CODE-REVIEW-266-r1.md`. Поверх этого в ветке issue лежит один новый коммит `7fd0ae4b` (автор — не Matysh/claude[bot], а `Codex <codex@local>`, тот же инструмент, что и во всех остальных коммитах-слайсах #266 — авторство не аномалия). Именно `git diff origin/dev...HEAD` = `git diff fd4bf0e9..HEAD` = ровно этот один коммит, и это предмет r2.
+
+## Скоуп r2 (дельта)
+
+`git diff 0b782ee7..HEAD --stat` (0b782ee7 — последний код-коммит перед r1-ревью; следующий коммит fd4bf0e9 — сам документ r1) даёт **один файл**: `docs/images/screenshots.json`, 22 строки (11 замен). `src/**` не тронут вообще.
+
+Изменение: `sourceFingerprint` (верхний уровень) и `sourceSha256` (в каждом из 10 сценариев) обновлены с `da2136b0…` на `49a41e2e…`. Ни один `imageSha256` не изменился ни на бит — сверено построчно (`grep -c imageSha256` diff = 0 совпадений с изменением). Коммит-сообщение: «Кадры прежние — golden и смоки подтверждают пиксельную идентичность».
+
+Это прямое следствие AC8 ТЗ («`check-docs` — зелёные») и §5 ТЗ («Fingerprint скриншотов обновится (src/\*\* меняется), кадры прежние») — ожидаемый и предусмотренный самим ТЗ шаг, а не новая работа.
+
+Дельта локальна (не ребейз, не смена контракта, не новая подсистема) — но, как показано ниже, чтобы понять, ПОЧЕМУ отпечаток вообще устарел, пришлось проверить состояние, из которого родился этот коммит, — и это привело к находке, которая тянется дальше границ самой дельты.
+
+## Как проверялось
+
+**Прогнано лично (не принято на слово):**
+
+- `npx tsc --noEmit` — зелёный.
+- `npm test` — 1319 тестов, 1318 pass / 0 fail / 1 skip.
+- `npm run build` (`tsc --noEmit && rollup -c`) — зелёный; `node scripts/bundle-sync.mjs` — три копии (`dist/houseplan-card.js`, `custom_components/houseplan/frontend/houseplan-card.js`, `demo/srv/assets/houseplan-card.js`) байтово идентичны, md5 `608da21ffb80bde51bfc8d321d0c267f`; `git status` по закоммиченной копии (`custom_components/...`) чист после пересборки — расхождения с деревом нет.
+- `node scripts/check-docs.mjs` — зелёный («7 files, 10 external links»), нужен, т.к. это прямой предмет дельты. Дополнительно перепроверено чтением исходника (`scripts/check-docs.mjs:134,145,147`): `sourceFingerprint` сверяется с `visualFingerprint(ROOT)` (детерминированный хеш `src/**` + фиксатор-инпуты), и **каждый** `imageSha256` сверяется с реальным байтовым содержимым PNG на диске (`sha256(readFileSync(imagePath))`) — то есть зелёный прогон подтверждает не только «строка совпала со строкой», а что закоммиченные картинки действительно совпадают со своими хешами.
+- **Контрольный эксперимент**: `git checkout 0b782ee7 && node scripts/check-docs.mjs` → `ERROR screenshot source fingerprint is stale`. То есть на коммите, который непосредственно предшествовал документу r1, `check-docs` был КРАСНЫМ. `dev` был зелёным по `fd4bf0e9` вплоть до появления `7fd0ae4b` — то есть job `docs` на `dev` был красным до этого фикса (ровно сценарий #230/#234/#237, который PROCESS.md прямо предостерегает не пропускать). Коммит `7fd0ae4b` это устранил; на HEAD `check-docs` зелёный — проверено выполнением, не заявлено.
+- `node scripts/smoke-select.mjs --base 0b782ee7 --head HEAD`: «Исполняемого frontend-диффа нет (`src/**/*.ts` не тронут)… смоки этим диффом не выбираются». Смоки на дельту не прогонял — выбирать нечего, это не пропуск проверки, а её неприменимость (см. текст инструмента).
+- `npm run golden:verify` (129 сцен) — прогнан **полностью, вручную**, несмотря на то что по объёму дельты (1 JSON-файл) это не обязательный гейт. Причина решения — ниже, в разделе «Аудит r1»: точность прежнего документа оказалась под вопросом, и главный критерий ТЗ (§1.3.1) стоило перепроверить независимо, а не наследовать бланково. Результат: **exit code 0** (`goldenRunFailed` не сработал — `demo/golden/run.mjs:885`), `git status --short demo/golden/baselines/` пуст — эталоны не переприняты. (Технический нюанс: команда была запущена в фоне через `| tail -40`, поэтому в захваченном логе видны только последние 40 строк, все «passed»; авторитетный сигнал — код возврата процесса и чистый git-статус baselines, а не подсчёт строк в обрезанном логе.)
+- Дополнительно (уже выходя за пределы формальной дельты, но по следу находки ниже): `scripts/dev/styles-diff.mjs` — прогнан на исходном `src/styles.ts` (SHA `30698d6e`, до начала #266) против пяти текущих файлов `src/styles/*.styles.ts` на HEAD. `diff before.json after.json` — **пустой**. Это независимое, самостоятельно посчитанное подтверждение refactor-only на итоговом (не промежуточном) коде.
+- `demo/smoke_plan_snap_overlay.mjs`, `demo/smoke_preloader.mjs` (обязательны по §1.3.6 ТЗ) и `demo/smoke_device_icon_design.mjs` (тот самый смок, который в CI поймал баг, исправленный `0b782ee7`) — прогнаны лично на HEAD, все три `OK`, ключевые поля (`forcedColorsStayReadable: true`, `anim: "none"`, `darkLockUsesGreenCoreAndDarkGlyph: true` и т.д.) присутствуют и истинны — не тавтологичный прогон.
+
+**Не прогонял (и почему):**
+- Полный набор `demo/smoke_*.mjs` (190 файлов) — `smoke-select.mjs` явно сообщил «нечего выбирать» для дельты; сверх дельты прогнал точечно три релевантных смока (см. выше) по следу находки, не весь набор — непропорционально для JSON-файла с метаданными.
+- `npm run invariants` — diff не трогает геометрию (рёбра, толщину, `layout`, `marker.space`, `open_spans`); неприменим.
+- `python -m pytest tests_backend -q` — `custom_components/**/*.py` не тронут (кроме синхронизированного бандла `custom_components/houseplan/frontend/houseplan-card.js`, не `.py`).
+- Performance-профили — не в AC, чувствительные пути не изменены.
+- Мутационный гейт (`scripts/mutation-gate.mjs`) целиком — не перезапускал; но его актуальность на HEAD проверена чтением (см. «Аудит r1» — расхождение с r1 найдено именно там).
+
+## Аудит r1 (почему пришлось выйти за рамки одного JSON-файла)
+
+Дельта `7fd0ae4b` существует только потому, что `0b782ee7` (фикс каскада: «host-gated groups belong to their owner surface») изменил `src/**` уже ПОСЛЕ того, как звучали числа в переписке по #266. Чтобы понять, корректно ли отражён этот фикс в принятом (уже смердженном) коде, я сверил конкретные числа из `CODE-REVIEW-266-r1.md` (документ смерджен в `dev` коммитом `fd4bf0e9`, идёт сразу после `0b782ee7`) с фактическим деревом на HEAD.
+
+**Результат: 4 из 4 проверенных точных чисел в CODE-REVIEW-266-r1.md не совпадают с HEAD.**
+
+| Факт | Заявлено в r1 | Факт на HEAD | Воспроизведение |
+|---|---|---|---|
+| `@media (prefers-reduced-motion: reduce)` блоков | «10 блоков в сумме по пяти файлам. Совпадает… с origin/dev» | **12** | `grep -c "@media (prefers-reduced-motion: reduce)" src/styles/*.styles.ts` → сумма 12; `test/styles-split.test.mjs:73` явно `assert.equal(…, 12)` |
+| Исключение юнита непересечения (AC4) | «единственное исключение (`.dev:focus-visible` base∩devices) обосновано» | **исключений нет** | `test/styles-split.test.mjs:62` → `assert.deepEqual(clashes, [])`, комментарий строки 59–61: «the exception list is empty» |
+| Дельта размера бандла (AC7) | «origin/dev = 1 291 440, HEAD = 1 291 458 → +18 байт» | **1 291 440 → 1 291 562, +122 байта** | `git show 0b782ee7:dist/houseplan-card.js \| wc -c` → 1291562 (совпадает с текущим HEAD, `git diff 0b782ee7..HEAD -- dist/` пуст) |
+| Мутантные якоря `mutation-gate.mjs` | «2 → base.styles.ts…; 3 → devices.styles.ts» | **все 5 → devices.styles.ts, 0 → base** | `grep -n "file: 'src/styles" scripts/mutation-gate.mjs` |
+
+Разгадка нашлась сразу: все четыре «заявленных» числа **точно совпадают** с состоянием на `0d62a48b` — коммите, который r1 сам назвал в строке «Материал» («…на SHA `0d62a48b`»). Но `0d62a48b` идёт **до** `0b782ee7` в истории ветки — то есть r1 не проверял именно тот код, который реально ушёл в `dev`, хотя его текст обсуждает контекст фикса (мотивацию, факт «якоря переадресованы») так, будто проверял. Пруф:
+
+```
+git show 0d62a48b:src/styles/base.styles.ts | wc -l                 # 248 — совпадает с r1
+git show 0d62a48b:dist/houseplan-card.js | wc -c                     # 1291458 — совпадает с r1
+git show 0d62a48b:scripts/mutation-gate.mjs | grep -c "base.styles"  # 2 — совпадает с r1
+```
+
+**Важно: это не означает, что смердженный код неверен.** Я независимо перепроверил итоговое (HEAD) состояние отдельно от заявлений r1 — `styles-diff.mjs` пуст, `golden:verify` 129/129 без переприёмки, `smoke_device_icon_design`/`smoke_plan_snap_overlay`/`smoke_preloader` зелёные, `npm test` 1318/0 — и оно действительно корректно. Фикс `0b782ee7` устранил реальный визуальный баг (пойманный CI-смоком до этого ревью), и после него код и тесты согласованы между собой. Но то, что «зелёный» вердикт r1 был подписан по числам чужого, более раннего SHA, а не по факту смердженного кода — это ровно случай, о котором предупреждает эта задача («Verified без названной команды и её результата доказательством не является»): команды были названы, но выполнены не на том дереве.
+
+Заведён отдельный процессный issue **#312** («Код-ревью #266/r1 подтвердил числа SHA до правки, а не смердженный код») — по аналогии с #311 из SPEC-REVIEW-266-r3. Это не Medium-находка «вне скоупа продукта» в смысле §12 (не дефект соседнего пользовательского поведения), а наблюдение о процессе ревью; тем не менее решил зафиксировать его отдельным issue, а не только в тексте, чтобы не повторить ошибку #171/#207 («оставили в тексте — не считается закрытием»). `docs/reviews/CODE-REVIEW-266-r1.md` не редактирую — исторический артефакт, уже смерджен.
+
+## Находки текущего раунда (r2)
+
+**Medium (в скоупе #266).** AC6a ТЗ (`docs/specs/266-split-styles.md:82`) требует буквально: «все **10** блоков `@media (prefers-reduced-motion: reduce)` присутствуют в итоговой склейке». Фактически в смердженном коде их **12** — `0b782ee7` разрезал 2 из 10 исходных обёрток, ранее ошибочно смешивавших зоны, на по-зонные копии (это и есть содержание фикса каскада). Автор явно обозначил это как открытый вопрос в хендоффе issue («микро-отступление от буквы AC6a «10» … на решение ревью»), но ни r1, ни спецификация это решение не зафиксировали — r1 просто (ошибочно) заявил, что число совпадает с ТЗ.
+
+Сам факт корректен и я его подтверждаю как ревьюер: 12 физических обёрток над теми же 10 «исходными» блоками правил — законный результат обязательного фикса, доказанный пустым `styles-diff.mjs` (ни одно правило не потеряло обёртку) и зелёными смоками `forced-colors`/`reduced-motion`. Но текст AC6a должен отражать факт, а не противоречить принятому коду. Дёшево чинится: заменить «10» на «12 (10 исходных обёрток, 2 из которых были смешанными по зонам и разрезаны на по-зонные копии при фиксе каскада `0b782ee7`; `styles-diff.mjs` подтверждает сохранность содержимого)» — формулировка по образцу того, как уже исправлен комментарий в `test/styles-split.test.mjs:69-72`.
+
+Других находок Medium/High в дельте r2 нет.
+
+**Low, не блокирует.** AC2 (`docs/specs/266-split-styles.md:77`) приводит «фактический замер»: base 248/chrome 381/devices 540/dialogs 1180/plan 1359. После `0b782ee7` реальные числа другие (base 165, chrome 391, devices 559, dialogs 1201, plan 1396 — те же файлы, но 2 группы правил уехали из `base` туда, где им и место). Порог AC2 (`каждый ≤1650, сумма ≤3874`) как ограничение **по-прежнему выполняется** (сумма 3731 ≤ 3874, максимум 1396 ≤ 1650) — это не нарушение критерия, только устаревшая иллюстрация. Не требую отдельной правки как блокирующей, но раз AC6a всё равно правится в этом раунде, разумно поправить и эту строку заодно (тот же абзац).
+
+## Что проверено и корректно
+
+- Дельта r2 сама по себе (`docs/images/screenshots.json`) — корректна: `sourceFingerprint`/`sourceSha256` пересчитаны верно (`check-docs.mjs` зелёный, проверяет реальные хеши файлов), `imageSha256` не менялся ни для одного из 10 сценариев — то есть заявление «кадры прежние» подтверждено данными, а не только текстом коммита.
+- AC1 (`styles.ts` ≤ 40 строк) — 19 строк, не изменилось.
+- AC3 (golden 129/129, эталоны не переприняты) — перепроверено лично на HEAD (см. выше), а не унаследовано молча.
+- AC5 (порядок сборщика) — покрыт `npm test` (`test/styles-split.test.mjs:44-47`), зелёный.
+- AC6 (refactor-only) — перепроверено лично инструментом сверки на итоговом (не промежуточном) коде: пустой diff.
+- AC7 (бандл ≤ 1 КБ) — фактическая дельта +122 байта (не +18, как ошибочно в r1, см. «Аудит r1»), но порог всё равно с большим запасом выполнен.
+- AC8 (`npm test`/`build`/`check-docs` зелёные) — все три подтверждены исполнением на HEAD.
+- Трейлеры коммита `7fd0ae4b`: `Issue: #266`, `User-Visible: no` — верно (изменение — метаданные документации, не продукт). CHANGELOG не тронут — согласовано.
+- Единственный источник числа: `docs/images/screenshots.json` хранит `sourceFingerprint` на верхнем уровне и per-scenario `sourceSha256`; `check-docs.mjs:147` явно сверяет, что все per-scenario значения равны верхнеуровневому — то есть это не 11 независимых источников одного факта, а один источник с проверяемой консистентностью. Пользовательских чисел (превью/подпись/подсветка) в этой дельте нет — `test/single-source-numbers.test.mjs` в объём `npm test` входит и прошёл, к этой дельте не относится содержательно.
+
+## Унаследовано из r1 (без повторной проверки по существу, но с независимой перепроверкой критичных фактов там, где дельта или аудит их коснулись)
+
+Документ: `docs/reviews/CODE-REVIEW-266-r1.md`, смерджен `fd4bf0e9`. Раздел не тронут дельтой r2 напрямую, но см. «Аудит r1» — часть заявленных в нём чисел не выдержала проверки, поэтому наследование здесь не бланковое:
+
+- **Принято без повторной проверки:** докстроки `docs/ARCHITECTURE.md` (раздел «Styles (#266)» — чисел не содержит, расхождению неоткуда взяться), состав скоупа/не-скоупа ТЗ §2, порядок слайсов §1.4, риски §4 — текстовые, не числовые утверждения, аудит их не задевает.
+- **Переподтверждено мной независимо в этом раунде, а не унаследовано:** AC3 (golden), AC6/AC6a (refactor-only diff + фактический счёт медиа-обёрток), AC7 (бандл), AC4 (юнит непересечения), мутантные якоря — именно потому, что аудит вскрыл неточности r1 в этих самых пунктах. Точные числа в этом документе — мои собственные, полученные на HEAD, не переписанные из r1.
+- **AC1, AC5** — унаследованы с лёгкой перепроверкой (число строк / порядок сборщика через `npm test`, который я прогнал целиком на HEAD, а не принял по описанию r1).
+
+## Вердикт
+
+**Жёлтый.** High: 0, Medium: 1 (в скоупе — текст AC6a `docs/specs/266-split-styles.md` расходится с принятым и корректным кодом, правка дешёвая: обновить формулировку на «12» с объяснением). Плюс Low-наблюдение (AC2 фактический замер, тот же абзац, можно поправить заодно) и отдельно заведённый процессный issue #312 (не блокирует #266, не Medium этой задачи).
+
+Сам продукт корректен: `check-docs`, `golden:verify` (129/129, без переприёмки), `styles-diff.mjs` (пусто), три обязательных/релевантных смока, `tsc`/`npm test`/`build`+3 копии бандла — все проверены мной лично на HEAD и зелёные. Блокирует переход только текстовое расхождение AC6a со спецификацией — исправление ограничивается формулировкой в `docs/specs/266-split-styles.md`, кода это не касается.