Possible fix for mate's window switcher.

docs/testing/window-switcher.md

@@ -0,0 +1,66 @@
+# MATE window switcher
+
+Marco exposes the selected window title as a status-bar accessible. While Alt
+is held, the old application can remain the X11 foreground client and the
+switcher need not send a focus event. Ordinary foreground and editable-text
+filters therefore cannot present its selection.
+
+Following Orca's switcher event contract, Cthulhu reads the container name on
+text insertion, selection change and showing-state gain. The accompanying
+accessible-name signal does not repeat the announcement. The native adapter
+handles this before routine background filtering and selected-child lookup.
+It requires the `marco` process identity, the Marco application name, a known
+visible/showing non-defunct status bar and a containing window on the same
+provider bus. It refreshes only that accessible before reading the selection.
+
+The application handler presents the title as transient speech and a Braille
+message. It preserves application/native focus, browser mode and review
+position, and rejects stale foreground epochs. Terminal handoff permits these
+window-manager announcements; screen lock and internal UI still block them.
+Normal key interruption and queued speech policy apply. No switcher state,
+native references, timers or polling are retained. Other window managers are
+outside this change.
+
+## Automated checks
+
+```sh
+go test ./internal/app -run '^TestMateWindowSwitcher' -count=1
+python3 tests/native_test_session.py env CTHULHU_NATIVE_WINDOW_SWITCHER=1 CTHULHU_NATIVE_BACKGROUND_EVENTS=1 go test -race ./internal/atspi -run '^TestNative(MateWindowSwitcherOutsideForeground|BackgroundEventFiltering)$' -count=1 -timeout=60s -v
+```
+
+The application regression reproduces the rejected non-focused status event
+from the reported log, repeated forward/reverse selections, showing and
+selection events, duplicate name rejection, stale/hidden/dead/impostor
+rejection, terminal handoff, screen lock and Braille flash requests. A later
+name change on the original control verifies that focus ownership survives.
+
+The private GTK fixture publishes a non-focusable status bar with Marco's
+application and process identity. It verifies that repeated insertions and a
+showing event survive native background filtering while the editor retains
+X11 foreground ownership. It models Marco's AT-SPI contract; it does not run
+the real MATE window manager. The existing background flood test checks both
+other-provider and same-provider inactive windows and zero content queries.
+All native checks use a disposable X server and accessibility bus.
+
+## Live acceptance
+
+After reviewing the diff and starting the candidate through the normal local
+launcher when ready:
+
+1. Open at least three differently titled windows. Hold Alt and press Tab
+   repeatedly. Confirm each selected title is spoken; repeat with Shift+Tab.
+2. Release Alt and confirm normal reading follows the chosen application.
+   Repeat from a terminal, and check that terminal delegation resumes.
+3. Open the switcher, cycle through titles and press Escape. Confirm reading
+   returns to the original control and review/navigation still work.
+4. With a browser open, check heading navigation, address-bar editing and
+   switching between two windows of the same application. Background status
+   updates must stay quiet.
+5. If using Braille, confirm each selection appears as a transient message
+   and normal application content returns after dismissal. Switcher output
+   must not appear while the screen is locked.
+
+Physical keys, audible speech, real Marco cycling/cancellation and physical
+Braille remain live acceptance checks. The original log contains an initial
+status insertion but no later insertions for its subsequent Tab presses; keep
+a fresh timed log if actual cycling still fails.