houseplan-card/docs/specs/154-touch-hover-reset.md

# Issue #154 — transient hover не залипает после touch

- **Issue:** https://github.com/Matysh/houseplan-card/issues/154
- **Статус документа:** готово к будущей реализации; issue остаётся на `S3-spec`
- **Приоритет:** P1
- **Тип:** bug/polish, обычный трек
- **Пользовательское изменение:** да

## 1. Проблема и требуемый результат

Мобильный браузер после tap может синтезировать mouse-события и сохранять CSS
`:hover`. Одновременно room hover в View управляется `mouseenter`/`mouseleave`,
а touch sequence не гарантирует `mouseleave`. Текущий `_notePointer()` закрывает
`_tip`, но не очищает `_hoverRoom` и не нейтрализует CSS hover.

После исправления touch/pen показывает только краткий pressed feedback на время
жеста. После его завершения transient hover отсутствует. Настоящие mouse и
trackpad сохраняют обычный hover, а на гибридном устройстве последующий mouse
input восстанавливает его после touch без reload.

## 2. Термины и границы состояния

**Transient hover** существует только из-за текущего hover-capable pointer:

- `_hoverRoom`, room fill/outline и room tooltip;
- device marker lift/shadow/brightness;
- opening, room label и control hover styles;
- dialog close/control hover;
- аналогичные чисто визуальные CSS `:hover` состояния общих View-компонентов.

Не являются transient hover и не очищаются этой задачей:

- `active`, `pressed` во время незавершённого pointer sequence;
- selected/checked/current состояния редакторов;
- working, unavailable, alarm, warning, Glow/pulse и иное HA-derived состояние;
- keyboard focus и `:focus-visible`;
- открытый по click/tap toggle-popover `hp-help`;
- открытый dialog либо выполненное action.

## 3. Scope

Обязательный охват основного View:

- room floor/fill/outline/label/tooltip;
- device marker, opening и vacuum marker;
- controls поверх плана и close/action controls диалога;
- tap комнаты из будущей #152;
- long press, pinch, multi-touch и pointer capture cancellation;
- touch → mouse/trackpad на гибридном устройстве;
- смена режима, visibility и lifecycle компонента.

Общие компоненты редакторов получают исправление, если используют тот же
pointer-modality gate без специальной адаптации. Полная поддержка touch-editing
остаётся вне scope согласно `docs/TOUCH-SUPPORT.md`.

## 4. Не входит в задачу

- изменение semantic device/room state;
- новый visual design hover/pressed/focus;
- изменение действий tap, long press или click;
- превращение `hp-help` в transient tooltip;
- исправление touch settings из #149;
- полная переработка gesture arbiter #152;
- глобальный `blur()`, снятие DOM focus либо synthetic click suppression,
  способный отменить пользовательское action.

## 5. Единый pointer-modality authority

Houseplan вводит один session-local источник фактической modality:

```text
unknown | mouse | touch | pen
```

Начальное значение — `unknown`; pointer-only hover при нём выключен. Переходы:

- trusted `PointerEvent` с `pointerType === 'mouse'` включает `mouse`;
- trusted `touch` включает `touch` и немедленно очищает transient hover;
- trusted `pen` включает `pen` и следует touch policy;
- следующий настоящий mouse/trackpad pointer event переводит touch/pen → mouse;
- смена mode/space, `visibilitychange` в hidden и disconnect очищают transient
  hover, не подменяя semantic state.

Media queries не являются authority: браузер может ошибочно сообщать
`(hover: hover)` после touch. Для включения CSS hover одновременно нужны:

1. последняя фактическая modality `mouse`;
2. hover/fine-pointer capability среды.

Компонент применяет единый class/data-attribute gate к View tree; дочерние
shadow components получают ту же modality явным property/attribute contract.
Независимые локальные детекторы и глобальный mutable singleton запрещены.

Modality не сохраняется в localStorage/config и не синхронизируется между
карточками. Она не обязана быть reactive product state, если один безопасный
DOM gate и явная очистка обновляются без лишнего full render.

## 6. Synthetic mouse policy

Touch-generated compatibility `MouseEvent` не может включить mouse modality.
Authority дают только Pointer Events с фактическим `pointerType`; существующие
`mouseenter`/`mouseleave` не меняют modality.

JS room hover переводится на `pointerenter`/`pointerleave` либо общий delegated
pointer path и устанавливается только для разрешённого mouse modality. Touch и
pen никогда не записывают `_hoverRoom`/`_tip` через hover path.

Не использовать произвольный таймаут «после touch игнорировать mouse N ms» как
основной механизм: он ломает быстрый touch → mouse сценарий и зависит от
браузера. Если конкретный браузер отправляет compatibility event как
`PointerEvent(pointerType='mouse')`, допускается только детерминированная
проверка provenance/capabilities этого же input sequence с unit/browser
доказательством; wall-clock suppression без идентичности sequence запрещён.

## 7. Очистка transient hover

Единый idempotent helper очищает только transient hover state. Он вызывается:

- в начале каждого touch/pen `pointerdown`;
- на соответствующих `pointerup` и `pointercancel`;
- при `lostpointercapture`;
- после terminal click/action path до следующего painted frame;
- при начале multi-touch/pinch и после его завершения/cancel;
- при mode/space change;
- при `document.visibilityState === 'hidden'`;
- при disconnect/remount boundary.

Повторный вызов — no-op и не должен создавать render loop. Pointer capture
снимается только владельцем gesture по текущему contract; hover cleanup не
отменяет service call, dialog open или room fit.

После touch terminal event pressed feedback очищается обычным gesture owner.
Transient hover не остаётся дольше одного animation frame и не используется для
имитации pressed.

## 8. CSS contract

Все пользовательски заметные View `:hover` selectors получают общий modality
gate. Как минимум это:

- room overlay/yard/styled fill;
- device normal/alarm lift, shadow и brightness;
- opening outline;
- room-label controls;
- stage controls/options;
- dialog close/action controls и общие card controls, видимые в View.

Один selector не должен случайно смешивать hover с semantic state. Если текущая
rule объединяет `:hover` и `:focus-visible`, её разделяют: mouse hover получает
modality gate, focus-visible остаётся без него. `:active`/explicit pressed styles
также остаются независимы.

Selectors редакторских handles можно оставить вне обязательного охвата, если
они не используются в View/shared component; решение фиксируется inventory в
review. Naked View `:hover` после изменения считается source-contract ошибкой.

## 9. JS hover и tooltip contract

- `_hoverRoom` и `_tip` не устанавливаются touch/pen событиями.
- `pointerleave` реальной мыши очищает принадлежащее target состояние.
- touch `pointerdown` очищает старый mouse hover до выполнения tap action.
- открытие/закрытие dialog не восстанавливает старый hover snapshot.
- tooltip, открытый keyboard focus либо explicit click contract, не должен
  ошибочно классифицироваться как hover; owner хранится явно.
- следующий mouse enter/move заново вычисляет current hit и показывает hover,
  а не восстанавливает устаревший room/device id.

Room fit #152 использует canonical hit resolver непосредственно из gesture
sequence и не зависит от `_hoverRoom`; очистка hover не должна терять room tap.

## 10. Touch, gestures и lifecycle

- Второй pointer немедленно исключает single-tap activation по действующему
  gesture contract и очищает hover.
- Pinch/long press могут выполнить своё существующее действие, но после terminal
  event не оставляют hover.
- `pointercancel`/lost capture всегда безопасны, даже если target удалён renderом.
- Tap → dialog → close не возвращает marker lift/shadow из пред-dialog frame.
- Pen tap следует touch policy; hover stylus не входит в обязательный контракт.
- Kiosk, light/dark theme, Flat/Isometric используют одинаковую modality policy.

Listener `visibilitychange` регистрируется/удаляется симметрично lifecycle и не
создаёт утечку при повторных mount/unmount.

## 11. Accessibility

- DOM focus не снимается touch cleanup helper.
- `:focus-visible` и keyboard tooltip/action продолжают работать независимо от
  последней pointer modality.
- Touch cleanup не меняет `aria-expanded`, `aria-pressed`, selection либо dialog
  focus trap.
- Mouse hover не является единственным способом получить обязательную
  информацию или действие.
- Reduced motion не влияет на state machine; pressed feedback #22 остаётся
  кратким и не превращается в hover.

## 12. Acceptance criteria

1. После touch tap на каждом обязательном View target transient hover исчезает
   не позднее следующего frame после завершения pressed feedback.
2. `_hoverRoom`/hover-owned `_tip` равны null после touch terminal event.
3. Device lift/shadow и CSS hover controls отсутствуют после tap/dialog close.
4. Working/alarm/unavailable/Glow/pulse/selected state не изменяется.
5. Pinch, long press, multi-touch, cancel и lost capture не оставляют hover.
6. Браузер с touch и ложным `(hover: hover)` не показывает sticky hover.
7. Настоящий desktop mouse hover визуально и функционально не изменён.
8. На hybrid device touch → mouse восстанавливает hover первым настоящим mouse
   pointer event без reload и без произвольной задержки.
9. Keyboard focus и `:focus-visible` сохраняются.
10. Cleanup не отменяет click action, dialog, #152 room fit или help popover.
11. Mode/space/visibility/disconnect очищают transient hover без listener leak.
12. В View/shared CSS не остаётся naked hover selector из inventory.

## 13. План тестирования

### Unit/source contract

- transitions `unknown → mouse/touch/pen → mouse`;
- compatibility MouseEvent не включает mouse modality;
- touch/pen down/up/cancel и lost capture вызывают idempotent cleanup;
- mode/space/visibility/disconnect lifecycle;
- cleanup очищает только hover-owned state;
- room hover gate и #152 hit независимы;
- CSS inventory: View hover selectors требуют modality gate, focus-visible — нет.

### Browser smoke

- реальный touch context/CDP touch input: room, device, opening, label, control;
- tap → dialog → close и tap при активном semantic device state;
- browser context с touch и `(any-hover: hover)`;
- two-finger pinch, long press, pointercancel и lost capture;
- touch room click-to-fit #152 без sticky room highlight;
- touch → hardware/simulated mouse pointer: hover снова появляется;
- desktop mouse enter/leave и keyboard Tab/Enter regression;
- Flat/Isometric, kiosk, light/dark и visibility round-trip.

Тест проверяет computed styles и JS state после painted frame, а не только
отсутствие class. `dispatchEvent(new MouseEvent(...))` не заменяет настоящий
touch browser scenario.

### Golden

- touch post-tap screenshot без hover, но с прежним semantic state;
- desktop mouse-hover и keyboard-focus screenshots;
- visual diff не переакцептует unrelated colors/shadows.

### Performance

- pointermove не вызывает full Lit update на каждый пиксель;
- modality gate не добавляет unbounded listeners/observers;
- canonical pan/pinch smoke сохраняет frame responsiveness;
- performance profile перед beta подтверждает отсутствие новых long tasks.

## 14. План реализации

1. Провести inventory JS state и View/shared CSS hover selectors.
2. Ввести component-local pointer modality authority и lifecycle cleanup.
3. Перевести room hover на pointer events с mouse gate.
4. Ввести общий CSS modality gate, разделив hover/focus/semantic rules.
5. Передать modality в обязательные shadow child components.
6. Добавить unit/source-contract и real-touch/hybrid browser tests.
7. Прогнать typecheck, unit и build; перед beta — smoke, golden, performance.

## 15. Документация и release-артефакты

Поскольку bug виден пользователю, implementation commit обязан иметь
`User-Visible: yes` и в том же коммите обновить:

- `docs/CHANGELOG.md` и `docs/CHANGELOG.ru.md`;
- `docs/TOUCH-SUPPORT.md` — pointer modality и отсутствие sticky hover;
- `docs/CANVAS.md` — hover/pressed/semantic ownership;
- `docs/TESTING.md` — real-touch и hybrid smoke contract.

Нужны reviewed touch post-tap, desktop-hover и keyboard-focus golden artifacts,
а также browser smoke report. Новых пользовательских строк не ожидается; если
появятся, обе локали и parity test обязательны.

## 16. Риски и откат

| Риск | Мера |
| --- | --- |
| Touch cleanup отменяет action | state-only helper, gesture smoke |
| Mouse hover пропадает на hybrid | event-derived transition back to mouse |
| Focus styling попадает под gate | отдельные selectors/source contract |
| Semantic state очищается как hover | явный inventory и state ownership tests |
| Pointermove вызывает rerender storm | DOM gate без full render per move |
| Lifecycle listener течёт | symmetric connect/disconnect test |

Откат возвращает прежние JS/CSS hover paths. Config, storage и backend data не
меняются; миграция и data rollback не нужны.

## 17. Принятые предположения

- `touch` и `pen` следуют одинаковой no-hover policy;
- initial `unknown` не включает pointer-only hover до фактической мыши;
- mouse modality определяется trusted PointerEvent, не compatibility MouseEvent;
- media query используется только вторым gate, а не источником modality;
- #152 room activation не должна читать `_hoverRoom` как selected hit;
- `hp-help`, focus-visible и semantic states не относятся к transient hover.