From 8e792dd4e248faa447100b20f1ee2353ae4300b0 Mon Sep 17 00:00:00 2001 From: Storm Dragon Date: Tue, 7 Apr 2026 16:29:42 -0400 Subject: [PATCH] Add mouse review Wayland backport design spec --- .../2026-04-07-mouse-review-wayland-design.md | 117 ++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 docs/superpowers/specs/2026-04-07-mouse-review-wayland-design.md diff --git a/docs/superpowers/specs/2026-04-07-mouse-review-wayland-design.md b/docs/superpowers/specs/2026-04-07-mouse-review-wayland-design.md new file mode 100644 index 0000000..bd4f04a --- /dev/null +++ b/docs/superpowers/specs/2026-04-07-mouse-review-wayland-design.md @@ -0,0 +1,117 @@ +# Guarded Mouse Review Wayland Backport + +## Summary + +Backport Orca's modern mouse review split into Cthulhu in a conservative way. Keep the current X11 `Wnck` plus `mouse:abs` implementation as the existing path. Add a second path that uses `Atspi.Device` pointer monitoring only when the local AT-SPI version is new enough and the compositor/device actually grants `POINTER_MONITOR`. If either condition fails, Cthulhu stays on the current behavior. + +This is explicitly an X-safe design. The X11 path remains first-class and unchanged in behavior. Wayland support is opportunistic and must fail closed. + +## Current State + +- Cthulhu mouse review currently depends on `Wnck` window lookup and `mouse:abs` events in [mouse_review.py](/home/storm/devel/cthulhu/src/cthulhu/mouse_review.py). +- Recent local changes already avoid importing `Wnck` on Wayland to suppress the terminal warning, but they do not add functional Wayland mouse review. +- Cthulhu already has an `Atspi.Device` for keyboard handling in [input_event_manager.py](/home/storm/devel/cthulhu/src/cthulhu/input_event_manager.py), which is the required foundation for an Orca-style pointer-monitor path. + +## Goals + +- Preserve existing X11 mouse review behavior. +- Add a guarded Wayland-capable path modeled on Orca's `Atspi.Device` pointer monitoring. +- Avoid startup warnings from `Wnck` on Wayland. +- Avoid enabling any new path unless support is positively confirmed at runtime. + +## Non-Goals + +- No full Orca mouse review rewrite beyond the pointer-monitor split. +- No removal or semantic change of the current X11 `Wnck` path. +- No OCR refactor beyond existing `Wnck` gating already added. +- No assumption that Wayland mouse review will work everywhere; unsupported compositors must remain a no-op. + +## Design + +### Capability Detection + +Mouse review will select its backend at runtime: + +1. If AT-SPI version is at least `2.60`, or the pre-release threshold Orca used (`2.59.90`), Cthulhu may try the new backend. +2. The new backend must call `set_capabilities(... | POINTER_MONITOR)` on the existing `Atspi.Device`. +3. The new backend is considered available only if `POINTER_MONITOR` is present in the returned capability set. +4. If any of those checks fail, Cthulhu uses the existing X11 path. + +This means X11 systems on older stacks continue to use the current implementation. Wayland systems with insufficient AT-SPI support do not partially enable mouse review. + +### InputEventManager Extension + +Extend [input_event_manager.py](/home/storm/devel/cthulhu/src/cthulhu/input_event_manager.py) with narrow pointer-monitor wrappers: + +- `enable_pointer_monitoring() -> bool` +- `start_pointer_watcher(callback) -> None` +- `stop_pointer_watcher() -> None` + +These wrappers should mirror Orca's error handling: + +- return `False` on missing device or `GLib.GError` +- never raise into callers +- leave existing keyboard handling unchanged + +No unrelated device-manager refactor is included in this pass. + +### Mouse Review Backend Split + +Update [mouse_review.py](/home/storm/devel/cthulhu/src/cthulhu/mouse_review.py) to maintain two internal paths: + +- Legacy path: + - existing `Wnck` window tracking + - existing `mouse:abs` listener + - existing absolute-coordinate flow +- New path: + - register a `pointer-moved` watcher on the `Atspi.Device` + - use the accessible object and local coordinates delivered by AT-SPI + - if the event source is an application, resolve the containing window from the app's accessible children + - otherwise use the event object directly + +The common object-presentation logic should stay shared as much as possible. Only the event source and coordinate acquisition differ. + +### Safety Rules + +- Do not change the old X11 path except for harmless factoring needed to share code. +- Do not force the new path on X11 systems that are currently using the legacy path successfully. +- If pointer monitoring disconnects, errors, or cannot be enabled, mouse review must behave as unavailable rather than falling into a broken mixed state. +- Existing `Wnck` suppression on Wayland remains in place. + +## Testing + +### Automated + +Add focused regressions for: + +- version/capability gating chooses the new backend only when allowed +- `enable_pointer_monitoring()` returns `False` on capability failure +- pointer watcher start/stop are no-ops when there is no device +- mouse review activation chooses the legacy backend when AT-SPI support is not available +- mouse review activation chooses the pointer-monitor backend when support is available + +Tests should mock AT-SPI rather than requiring a compositor. + +### Manual + +X11: + +- mouse review still enables and behaves as before +- no regressions in pointer routing or reviewed object presentation + +Wayland: + +- no `Wnck` warning on startup +- mouse review only enables when AT-SPI pointer monitoring is actually available +- if supported, pointer hover review works without breaking keyboard handling +- if unsupported, failure is clean and explicit rather than noisy or partially broken + +## Risks + +- The local environment here is still on AT-SPI `2.58.4`, so the new backend cannot be exercised live in this workspace. +- The guarded design limits that risk by preserving the existing path and enabling the new path only under the same runtime conditions Orca used. +- The main regression risk is accidental interaction with Cthulhu's existing keyboard `Atspi.Device`; that is why the change is limited to small wrappers plus mouse-review-specific watcher usage. + +## Recommendation + +Implement the guarded dual-path backport and stop there. Do not port broader Orca mouse review refactors in the same pass.