Add mouse review Wayland backport design spec

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.