Release v1.62.0-beta.4 candidate

2026-09-29 03:09:36 +00:00 · 2026-08-12 10:19:51 +03:00
parent 8a417539e0
commit 4dc3fdef36
30 changed files with 1459 additions and 545 deletions
@@ -100,7 +100,10 @@ the same profiler available between stable promotions.
   and `floating-surface-controller.ts` fallback/portal lifecycle,
   prefer the browser top-layer Popover API and use a real dialog-owned portal
   when that API is unavailable. Help text is localized by the owning card so
-   two cards with different explicit languages remain independent.
+   two cards with different explicit languages remain independent. A help
+   affordance exists only when both its localized body and complete accessible
+   label are non-empty; the card factory and `hp-help` enforce this independently,
+   so incomplete content cannot leave a dead focus target or a layout gap.

 ## Coordinate system

@@ -793,6 +796,11 @@ hash falls back to the default.
  action `cover` remains accepted and losslessly round-tripped as a legacy
  origin until the user deliberately changes the selector. An absent action on
  a primary `light.*` likewise stays absent on an untouched Open → Save.
+  `POWER_ADAPTERS` is the explicit domain allow-list and carries per-entity HA
+  feature masks where a domain-wide service is not capability proof. The
+  service catalog is a second fail-closed guard. A click resolves the current
+  marker by id rather than using a retained #73 visual snapshot; the snapshot
+  remains valid only for read-only presentation.
 - **Resolved device state** (2026-08-06): HA provides states per entity, not
  one state per device. `resolvedDeviceStateEntities` therefore starts from
  uncategorised registry entities, resolves one functional role (whole-device
@@ -2,6 +2,32 @@

 ## Unreleased

+## v1.62.0-beta.4 — 2026-08-12
+
+- Fixed contextual help showing a dead icon when its explanation was absent.
+  Incomplete help content is now omitted entirely, and the plain `?` glyph was
+  replaced with the consistent outlined circled-question icon
+  ([#68](https://github.com/Matysh/houseplan-card/issues/68)).
+- Hardened universal **Toggle state** after the beta code review. Climate,
+  water-heater, siren, camera, media-player and legacy-vacuum actions now
+  require the exact HA entity capability bits as well as a live service;
+  clicks resolve current controls instead of a retained visual frame, and a
+  disabled legacy cover keeps its original, explainable target
+  ([#94](https://github.com/Matysh/houseplan-card/issues/94)).
+- Fixed the device editor showing **Device card** for a lamp whose effective
+  default action is **Toggle state**. Untouched actions now follow the current
+  preview entity in real time, while explicit choices and lossless legacy
+  storage remain unchanged
+  ([#97](https://github.com/Matysh/houseplan-card/issues/97)).
+- Fixed **Device card** taps doing nothing on compound curtain/cover devices.
+  The local House Plan card now opens independently of a momentary HA registry
+  revalidation, while HA more-info and service actions retain their safety gate
+  ([#96](https://github.com/Matysh/houseplan-card/issues/96)).
+- Fixed an editor-close race after a same-route technical remount. A visible
+  editor now closes on the first press even while write permission is still
+  resolving; the late server response can no longer reopen it
+  ([#95](https://github.com/Matysh/houseplan-card/issues/95)).
+
 ## v1.62.0-beta.3 — 2026-08-12

 - Replaced the separate Toggle and cover actions with one universal **Toggle
@@ -8,6 +8,32 @@

 ## Unreleased

+## v1.62.0-beta.4 — 2026-08-12
+
+- Исправлено отображение неработающего значка подсказки, когда самого текста
+  подсказки нет. Неполная подсказка теперь целиком скрывается, а обычный символ
+  `?` заменён на единообразную контурную иконку «вопрос в кружке»
+  ([#68](https://github.com/Matysh/houseplan-card/issues/68)).
+- Усилена надёжность универсального **«Переключить состояние»** после код-
+  ревью беты. Для climate, бойлеров, сирен, камер, медиаплееров и legacy-
+  пылесосов теперь проверяются точные capability bits сущности и наличие
+  сервиса; клик использует актуальные controls, а не сохранённый визуальный
+  кадр, и деактивированная legacy-штора сохраняет прежнюю объяснимую цель
+  ([#94](https://github.com/Matysh/houseplan-card/issues/94)).
+- Исправлено отображение **«Карточка устройства»** у лампы, фактическим
+  действием которой по умолчанию является **«Переключить состояние»**.
+  Нетронутая настройка теперь следует за актуальной ведущей сущностью в
+  предпросмотре, не меняя явный выбор пользователя и lossless-хранение legacy
+  ([#97](https://github.com/Matysh/houseplan-card/issues/97)).
+- Исправлено бездействие пункта **«Карточка устройства»** у составных устройств
+  штор и жалюзи. Локальная карточка House Plan теперь открывается независимо от
+  кратковременной повторной проверки реестра HA, а HA more-info и сервисные
+  действия сохраняют защитную проверку ([#96](https://github.com/Matysh/houseplan-card/issues/96)).
+- Исправлена гонка при закрытии редактора после технического ре-маунта на том
+  же маршруте. Видимый редактор теперь закрывается с первого нажатия, даже если
+  право записи ещё уточняется; поздний ответ сервера больше не открывает его
+  повторно ([#95](https://github.com/Matysh/houseplan-card/issues/95)).
+
 ## v1.62.0-beta.3 — 2026-08-12

 - Отдельные действия Toggle и управления шторами объединены в одно
@@ -1,18 +1,18 @@
-<!-- release: v1.62.0-beta.3 -->
+<!-- release: v1.62.0-beta.4 -->

 ## Основное

- Добавлено универсальное действие «Переключить состояние» с точным предпросмотром цели.
- При возвращении к карточке восстанавливается пространство, но всегда открывается режим просмотра.
- Исправлен Glow от источника внутри толстой стены или внешнего проёма.
+- Редактор устройств теперь закрывается с первого нажатия.
+- Исправлены действия ламп и составных устройств штор; универсальное переключение точнее учитывает возможности Home Assistant.
+- Значок подсказки больше не показывается без текста и заменён на «вопрос в кружке».
 - Мелкие исправления и улучшения.

 ## Highlights

- Added a universal Toggle state action with an exact target preview.
- Returning to the card restores the space but always opens View mode.
- Fixed Glow from a source embedded in a thick wall or exterior opening.
+- The Device editor now closes on the first press.
+- Fixed lamp and compound-cover actions; universal toggle now observes Home Assistant capabilities more precisely.
+- Help is no longer shown without explanatory text and now uses the circled-question icon.
 - Small fixes and improvements.

-[Полный список изменений на русском](https://github.com/Matysh/houseplan-card/blob/v1.62.0-beta.3/docs/CHANGELOG.ru.md)
-· [Full changelog in English](https://github.com/Matysh/houseplan-card/blob/v1.62.0-beta.3/docs/CHANGELOG.md)
+[Полный список изменений на русском](https://github.com/Matysh/houseplan-card/blob/v1.62.0-beta.4/docs/CHANGELOG.ru.md)
+· [Full changelog in English](https://github.com/Matysh/houseplan-card/blob/v1.62.0-beta.4/docs/CHANGELOG.md)
@@ -21,8 +21,8 @@ metadata). Only an explicit owner-approved emergency hotfix may skip this gate.

 | Item | State |
 |---|---|
-| Version | **v1.62.0-beta.3** everywhere (manifest, const.py, package.json, CARD_VERSION) — prerelease candidate for issues #92–#94 |
-| Current local cycle | The v1.62.0-beta.3 candidate makes Glow fail dark when a source is embedded inside final opaque thick-wall geometry, including exterior openings (#92); persists only the selected space across real HA navigation and always returns in View while preserving same-route technical remount continuity (#93); and replaces separate toggle/cover choices with one explained `Toggle state` resolver shared by preview, click, confirmation and cover presentation (#94). Exact bindings, partial groups, secure no-op and lossless legacy/default records are explicit contracts. Issue #89 remains specification-only. |
+| Version | **v1.62.0-beta.4** everywhere (manifest, const.py, package.json, CARD_VERSION) — prerelease candidate for issues #95–#97 plus #68/#94 hardening |
+| Current local cycle | The v1.62.0-beta.4 candidate fixes three interaction/UI races: explicit mode commands cancel an older `_pendingNavMode`, so the Device editor closes on the first press (#95); the local House Plan device card opens independently of transient HA registry revalidation for compound covers (#96); and an untouched tap-action selector follows the current preview primary, keeping a lamp's label aligned with its effective action (#97). The #94 review additionally makes domain adapters fail closed on exact HA capability bits and service availability, resolves clicks from live controls and preserves disabled legacy-cover identity. The #68 review suppresses incomplete help at both factory and component boundaries, removes the hard-coded English ARIA fallback and uses the outlined circled-question MDI icon. Targeted prerelease gates cover these surfaces; issue #89 remains specification-only. |
 | Workflow | Owner's rule since 2026-08-07: ordinary fixes/features are made **locally, without tests and without commits**. A requested pre-release gets a production build plus the smallest targeted unit/smoke set covering the changed surfaces, one tested `dev` commit/tag and a GitHub Release with `prerelease=true`; `main` stays untouched. The complete local frontend/backend/smoke gate runs only before a stable release, after which `main` is fast-forwarded to the exact tested `dev` SHA and the GitHub Release uses `prerelease=false`. Release bodies are short and bilingual (Russian first): only significant user changes get individual bullets, while minor/code-only work is grouped as `Мелкие исправления и улучшения` / `Small fixes and improvements`; every body ends with separate links to the Russian and English changelogs. Detailed RU/EN changelog bullets may link the corresponding closed GitHub Issues; open or partially delivered issues are never presented as shipped. Telegram announcements are sent only for stable releases; beta and RC publication is silent. `docs/RELEASE-NOTES.md` is the current canonical body instance; `npm run release:prerelease -- <tag> --issues=… --yes` is the primary local publication path and the manual `Publish prerelease` workflow is its GitHub-only equivalent once present on `main`. Nothing is copied to the home instance by hand |
 | GitHub | https://github.com/Matysh/houseplan-card — [Issues](https://github.com/Matysh/houseplan-card/issues) are the canonical task records and the linked [Project v2](https://github.com/users/Matysh/projects/1) is the canonical priority/status view; both must stay current. `main` carries stable releases; pre-release tags may point directly at `dev`. Work lands on `dev` and is merged into `main` for a stable release, so `dev` is normally equal to or ahead of `main`, never behind. Push via SSH key `ha_jb` (remote git@github.com:…); API releases via the fine-grained PAT in `~/.git-credentials` (Contents R/W, issued 2026-07-23) |
 | CI | Prerelease publication requires a green exact-SHA Validate: frontend/backend, smoke (including the #73 rAF frame sampler), golden, HACS/Hassfest and a short absolute-ceiling performance smoke. Obsolete same-ref Validate runs are cancelled. Full seven-sample base/candidate performance moved to `performance.yml` (`main` push, weekly, manual); stable release assets fail closed unless Validate and Full Performance are green for the exact tagged SHA and the stable-only CDP compositor screencast finds no empty/black presented frame. |
@@ -416,9 +416,14 @@ separately promised workflows:
      domain toggle. Confirmation re-resolves current state but cancels if the
      target set changed. Opening and saving an untouched legacy `cover` or an
      absent light default preserves the original token/absence; an intentional
-      selector edit writes `toggle`
+      selector edit writes `toggle`. Feature-gated climate/water-heater/siren/
+      camera/media-player/legacy-vacuum entities require their exact HA bits;
+      an empty service catalog is unsupported. If #73 retains an older visual
+      device while live controls change, click calls only the current controls
      [auto: test/device-toggle.test.mjs + smoke_cover_tap +
-      smoke_cover_not_primary + backend action-schema parity]
+      smoke_cover_not_primary + smoke_controls + backend action-schema parity]
+      The synthetic HA fixture publishes its service catalog explicitly, so
+      browser checks exercise the same fail-closed resolver as production
 - [ ] A cover is NEVER painted (dev, owner 2026-08-04): «у штор не должно быть
      жёлтой подложки никогда, индикация открыто/закрыто за счёт морфинга
      иконки». Walk one curtain through closed / open / ajar / opening /
@@ -723,7 +728,9 @@ separately promised workflows:
      out of the box — no per-device setting needed; the device dialog shows
      "Toggle" as its effective default; devices where light is a side
      function (kettle: primary = sensor) keep the Device-card default;
-      explicit per-device "Device card" wins over the default [auto: smoke_light_default_tap]
+      an untouched open dialog follows a newly resolved light primary instead
+      of retaining a stale Device-card label (#97); explicit per-device
+      "Device card" wins over the default [auto: smoke_light_default_tap]
 - [ ] Derived walls cut too (v1.38.4): in the Plan editor the derived wall
      segments (.seg) no longer run solid through an open stretch — only the
      dash remains there [auto: smoke_openwall]
@@ -735,11 +742,17 @@ separately promised workflows:
      `mode` and is rewritten without it. A `#space=` deep link beats the saved
      space but still opens View. A technical same-route remount preserves an
      unfinished editor/dialog, while a real route departure clears both
-      [auto: smoke_nav_persist + smoke_warm_dialogs]
+      [auto: smoke_nav_persist + smoke_warm_dialogs]. During a pending
+      `can_write` warm restore, one press on the visible editor close button
+      cancels the deferred editor and a late response cannot reopen it (#95)
+      [auto: smoke_nav_persist]
 - [ ] Tap action cleanup + right click (v1.38.1, #94): the per-device action
      list has four options (Device card / HA more-info / Toggle state / Run),
      no separate cover or "card default" option — the card editor's global
      tap option is gone and ignored;
+      Device card opens locally for compound curtains/covers even during a
+      transient registry revalidation and calls no HA service (#96)
+      [auto: smoke_cover_not_primary];
      right click on an icon in VIEW opens HA more-info (native menu kept in
      editors; virtual w/o entity → device card) [auto: smoke_tap_ctx]
 - [ ] Binding section redesign (v1.38.0): two radios — Virtual / Pick from
@@ -2031,6 +2044,19 @@ require hands on real hardware — they remain for the human pass.
      config/space/source changes [auto: editor/preloader smokes; performance
      profile for a dense plan].

+## Contextual help (issue #68, v1.62)
+
+- [ ] A setting with complete RU/EN help body and ARIA copy shows one 32 px
+      desktop / 40 px coarse-pointer button with the outlined circled-question
+      icon. Mouse hover, keyboard focus and tap open the same text surface
+      [auto: `smoke_help_affordance`].
+- [ ] Empty or whitespace-only help body produces no trigger. A non-empty body
+      without a complete ARIA label also produces no trigger; neither case adds
+      a tab stop or reserves visible space [auto: `smoke_help_affordance`].
+- [ ] Escape, outside pointer, owning-dialog scroll, toast and a competing colour
+      picker close help in the documented order. The Popover and portal fallback
+      paths stay inside the visual viewport [auto: `smoke_help_affordance`].
+
 ## Hiding layers: decor, openings, virtual walls (docs/UX-MODES.md, dev, unreleased)

 - [ ] **«Скрыть декоративный слой»** (owner 2026-08-05): a space with lines,
@@ -138,6 +138,13 @@ Lovelace **пересоздаёт элемент карточки** — выбр
 `_restoreZoom()` — центрирующее восстановление осталось только для настоящей
 навигации (хеш/`LS_NAV` привели на другое пространство).

+Явная команда пользователя всегда сильнее ещё не применённой памятки. Пока
+backend уточняет `can_write`, старый DOM редактора может оставаться видимым, а
+новый экземпляр уже fail-closed находится в Просмотре и держит режим только в
+`_pendingNavMode`. Любой вызов `_setMode()`, включая повторный `view` от
+видимого крестика, сначала отменяет этот pending: поздний ответ сервера не
+имеет права снова открыть уже закрытый редактор (#95).
+
 Диплинк `#space=<id>` — явная навигация и по-прежнему сильнее памятки. Он
 выбирает пространство, но, как и обычный возврат на карточку, не включает
 редактор.
@@ -1,8 +1,8 @@
-# 068 — Подсказки к настройкам: переиспользуемый «?» в любом диалоге
+# 068 — Подсказки к настройкам: переиспользуемая кнопка помощи в любом диалоге

 - Issue: **#68**
 - Приоритет: P2, polish
- Статус ТЗ: **реализовано локально; проверки отложены до пре-релиза** (ревизия 4)
+- Статус ТЗ: **выпущено в v1.62.0-beta.1; локально усилено после ревью** (ревизия 5)
 - Связано: #30 (информационная архитектура диалогов), #31 (доступность),
  #62 (инфраструктура i18n), #85 (тесты должны уметь падать)
 - Область: общий компонент `hp-help`, фабрика вызова Houseplan Card, `hp-dialog`,
@@ -22,6 +22,13 @@ dialog-owned portal в composed focus traversal и запрещает Escape п
 каждом попадании фокуса. Статический scanner дополнительно запрещает сочетать
 `title=` и `_help()` на одном host-контроле.

+Ревизия 5 по полному code review запрещает «мёртвый» affordance: кнопка помощи
+не существует в DOM, если отсутствует или пуста хотя бы одна из двух обязательных
+локализованных строк — текст подсказки либо полная ARIA-подпись. Фабрика проверяет
+пару до создания host, а сам `hp-help` повторяет защиту для прямого и динамического
+использования. Визуальный знак — MDI `help-circle-outline` («вопрос в кружке»), а не
+зависящий от системного шрифта символ `?`.
+
 ---

 ## 0. Что изменено ревью 2026-08-11
@@ -1,7 +1,7 @@
 # Issue #94 — универсальное действие «Переключить состояние»

- **Статус:** ТЗ принято владельцем; редакция 2 после технического ревью
-  2026-08-12; готово к реализации
+- **Статус:** реализовано в `v1.62.0-beta.3`; полный code-review и hardening
+  capability/live-target contracts включены в кандидат `v1.62.0-beta.4`
 - **Issue:** https://github.com/Matysh/houseplan-card/issues/94
 - **Область:** frontend, marker action model, HA service dispatch, backend
  compatibility, i18n, документация и QA
@@ -216,6 +216,13 @@ unavailable/disabled/secure либо исчез service/adapter), действи

 ### 6.4. Save

+Отображаемое значение select для нетронутого action является живой эффективной
+проекцией, а не копией, зафиксированной при открытии диалога. Оно пересчитывается
+из `originalTapAction` и актуального `previewDevice.primary` на каждом render:
+если HA позднее уточнил ведущую сущность как `light.*`, UI сразу показывает
+`Переключить состояние`, как и runtime. После явного изменения select значение
+становится пользовательским и больше автоматически не меняется.
+
 - `toggle` разрешено сохранять всегда, даже при `kind: none`.
 - Save не требует target.
 - После повторного открытия явно выбранный action остаётся `toggle`; legacy
@@ -443,6 +450,14 @@ siren, vacuum, water_heater и других domains. Появление ново
 toggle только из-за наличия `turn_on`: их запуск остаётся action `run`.
 Список adapters и state semantics не копируется по renderer/click paths.

+Реализация использует один декларативный `POWER_ADAPTERS`. Для доменов, где
+Home Assistant регистрирует service на весь domain, но ограничивает конкретную
+entity через `supported_features`, adapter требует точные bits: climate
+`TURN_OFF/TURN_ON`, water heater `ON_OFF`, siren `TURN_OFF/TURN_ON`, camera
+`ON_OFF`, media player `TURN_OFF/TURN_ON` и legacy vacuum `TURN_OFF/TURN_ON`.
+Отсутствующий или пустой `hass.services` не считается оптимистическим
+разрешением.
+
 Для automation hint обязан говорить «включить/выключить автоматизацию», а не
 «запустить»: запуск остаётся отдельным action `run`.

@@ -582,9 +597,11 @@ cover indicator, который управляет morph/activity marker. Отд
 | Весь device disabled | Marker скрыт по действующему contract; action/config не стираются |
 | Friendly name изменён | Hint обновляет имя, entity id остаётся тем же |
 | Integration добавила более сильную role entity | Auto-target device binding может измениться; hint отражает результат |
+| Пока #73 показывает последний цельный visual frame | Click повторно находит текущий marker по id и разрешает action/controls только из live devices; исчезнувший marker даёт no-op |
 | Explicit controls + own relay | Controls полностью выигрывают; relay не fallback |
 | Default light + controls | Собственный light default сохраняется; controls не перехватывают tap |
 | Legacy cover + controls | До явного изменения action сохраняется старая cover-цель; controls игнорируются |
+| Legacy device содержит disabled и active cover | Active cover имеет приоритет; disabled cover используется только как историческая объяснимая цель, если активной больше нет |
 | Group: one on, others off | Turn off all |
 | Group: all off | Turn on all |
 | Group: часть unavailable/missing | Команда для доступного подмножества; hint перечисляет пропущенные цели |
@@ -70,10 +70,10 @@ GitHub Issues и GitHub Projects (v2) остаются единственным
 | [#54](https://github.com/Matysh/houseplan-card/issues/54) Zigbee topology overlay | [054-zigbee-topology-overlay.md](054-zigbee-topology-overlay.md) | research + adapter contract |
 | [#55](https://github.com/Matysh/houseplan-card/issues/55) Independent Glow overlay | [055-independent-glow-overlay.md](055-independent-glow-overlay.md) | реализовано в v1.61.0-beta.2; #61 — v1.61.0-beta.3 |
 | [#56](https://github.com/Matysh/houseplan-card/issues/56) Static room color | [056-static-room-color.md](056-static-room-color.md) | реализовано в v1.61.0-beta.3 |
-| [#68](https://github.com/Matysh/houseplan-card/issues/68) Подсказки к настройкам | [068-help-affordance.md](068-help-affordance.md) | реализовано локально; проверки на пре-релизе |
+| [#68](https://github.com/Matysh/houseplan-card/issues/68) Подсказки к настройкам | [068-help-affordance.md](068-help-affordance.md) | выпущено в v1.62.0-beta.1; локально усилено после ревью |
 | [#84](https://github.com/Matysh/houseplan-card/issues/84) Источник «Всегда» без сущности HA + [#88](https://github.com/Matysh/houseplan-card/issues/88) ведущая сущность | [084-passive-forced-light-sources.md](084-passive-forced-light-sources.md) | реализовано локально вместе; ожидает prerelease/CI gate |
 | [#90](https://github.com/Matysh/houseplan-card/issues/90) Управляемый бейдж со значением | [090-device-value-badge.md](090-device-value-badge.md) | реализовано локально; ожидает prerelease/CI gate |
-| [#94](https://github.com/Matysh/houseplan-card/issues/94) Универсальное действие «Переключить состояние» | [094-universal-state-toggle.md](094-universal-state-toggle.md) | реализовано в v1.62.0-beta.3 по редакции 2; следующий gate — beta feedback и code review |
+| [#94](https://github.com/Matysh/houseplan-card/issues/94) Универсальное действие «Переключить состояние» | [094-universal-state-toggle.md](094-universal-state-toggle.md) | реализовано в v1.62.0-beta.3; review/hardening включены в кандидат v1.62.0-beta.4 |

 ## Правило актуализации