cthulhu/docs/superpowers/specs/2026-04-07-mouse-review-wayland-design.md

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.
• 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, 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 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 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.