From 89950e9944d24dd741aba8ad3613d25fe8f7cb22 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 29 Aug 2026 13:02:41 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D1=81=D0=BA=D0=B0=D0=B7=D0=B0=D1=82?= =?UTF-8?q?=D1=8C,=20=D1=87=D1=82=D0=BE=20=D0=BA=D0=BE=D0=BC=D0=BF=D0=B0?= =?UTF-8?q?=D0=BA=D1=82=D0=BD=D0=B0=D1=8F=20=D0=BA=D0=B0=D1=80=D1=82=D0=BE?= =?UTF-8?q?=D1=87=D0=BA=D0=B0=20=D0=BD=D0=B5=20=D1=81=D1=82=D1=80=D0=BE?= =?UTF-8?q?=D0=B8=D1=82=20=D0=BF=D1=83=D0=BB=D1=8B=20=D1=81=D0=B2=D0=B5?= =?UTF-8?q?=D1=82=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Внешний пользователь завёл #370 как баг: в houseplan-space-card нет теней от стен, хотя в houseplan-card они есть. Разбор показал, что кода это не касается — ограничение намеренное и записано в src/space-render.ts:353 («the compact card intentionally has no live radial pools»). visibilityPolygon из src/light-visibility.ts импортируют ровно два файла, houseplan-card.ts и houseplan-editor-runtime.ts; space-render.ts не импортирует его вовсе. Пулов нет, а тень существует только как форма пула — затенять нечего. Но претензия справедлива, просто адресована не туда. Единственная запись о намеренности жила в комментарии исходника, которого пользователь видеть не может, а руководство обещало обратное: «маркеры используют те же состояния, значения, тревоги и эффекты, что полный план» — про свет ни слова. В LIGHT.md про компактную карточку тоже не было ничего. Человек полез в код именно потому, что документация молчала, и сам корректно предположил, что это может быть намеренно. Теперь сказано в трёх местах: оба руководства и LIGHT.md, с причиной — пулы это самая дорогая часть отрисовки, у неё свой перф-воркфлоу и бюджеты, и компактная карточка платит за дешевизну именно ими. Issue: #370 User-Visible: no --- docs/LIGHT.md | 17 +++++++++++++++++ docs/USER-GUIDE.md | 8 ++++++++ docs/USER-GUIDE.ru.md | 7 +++++++ 3 files changed, 32 insertions(+) diff --git a/docs/LIGHT.md b/docs/LIGHT.md index ef81fe1b..19722599 100644 --- a/docs/LIGHT.md +++ b/docs/LIGHT.md @@ -246,6 +246,23 @@ The complete UI and runtime truth table lives in - Golden: `lighting-opaque-glow-two-doorways-dark` and the other `lighting-*` scenes, re-shot and approved 2026-08-11. +## Which surfaces render pools + +Pools — and therefore wall shadows — exist on the **full plan only**: +`houseplan-card` and the geometry editors. `visibilityPolygon()` +(`src/light-visibility.ts`) is imported by those surfaces and by nothing else. + +`houseplan-space-card` takes the static path (`renderSpaceStatic()` in +`src/space-render.ts`) and deliberately has no live radial pools; it shares the +room fills and the independent data/base projection with the full plan, so a lit +room is painted flat. Without a pool there is no shape to occlude, so the compact +card shows no wall shadows. This is a cost decision, not an omission: the pool +layer is the heaviest thing the product renders — it owns its own performance +workflow, budgets and a per-run smoke (`large-house-glow-overlay-v1`). + +Reported from the field as a bug (#370), because the user guide promised that +markers share everything with the full plan and said nothing about light. + ## Performance The large cold geometry recalculation (20 rooms, 20 partitions, 14 columns, diff --git a/docs/USER-GUIDE.md b/docs/USER-GUIDE.md index 42eeb612..57d55c76 100644 --- a/docs/USER-GUIDE.md +++ b/docs/USER-GUIDE.md @@ -761,6 +761,14 @@ text sizing. `cycle` enables automatic space changes; interaction pauses it for hover, drag, more-info or actions. A footer button opens the full plan. Use it for compact dashboard navigation, not for home control. +**Light is deliberately different here.** The compact card paints the flat fill +of a lit room and the data-mode fills, but it builds no radial light pools from +the lamps. Consequently it draws no wall shadows either: a shadow exists only as +the shape of a pool, and with no pools there is nothing to occlude. The full plan +computes the pools and how walls, openings and columns block them +(`docs/LIGHT.md`); that is the most expensive part of the render, and it is +exactly what the compact card trades away for being cheap. + ```yaml type: custom:houseplan-space-card space: ground diff --git a/docs/USER-GUIDE.ru.md b/docs/USER-GUIDE.ru.md index 6bdde42f..0d51a3db 100644 --- a/docs/USER-GUIDE.ru.md +++ b/docs/USER-GUIDE.ru.md @@ -1482,6 +1482,13 @@ House Plan скрывает только собственную шапку. Ша план, но не открывают подсказки или more-info. Единственный интерактивный элемент — нижняя кнопка перехода. +**Свет здесь другой, и это намеренно.** Компактная карточка рисует ровную +заливку освещённой комнаты и заливки data-режимов, но не строит радиальные пулы +света от ламп. Значит, на ней нет и теней от стен: тень существует только как +форма пула, и без пулов затенять нечего. Полный план считает пулы и перекрытие +светом стен, проёмов и колонн (`docs/LIGHT.md`) — это самая дорогая часть +отрисовки, и компактная карточка платит за свою дешевизну именно ею. + ```yaml type: custom:houseplan-space-card space: ground_floor