cthulhu/docs/testing/flatpak-foreground.md

Flatpak foreground accessibility

The Python master reference's script_utilities.py:canBeActiveWindow requires active, showing, non-iconified state. It does not require X11 and AT-SPI process IDs or window rectangles to agree. Go's additional correlation checks exposed two Flatpak cases:

• _NET_WM_PID can be relative to the application's PID namespace. The Xorg foreground reader now prefers XRes 1.2's local connection PID. It retains the property as a fallback when server-side lookup is unavailable.
• AT-SPI's process query returns the D-Bus connection owner, which can be a proxy. The adapter accepts different processes only when their /proc/PID/root/.flatpak-info files identify the same application and running instance. Active state, geometry and existing window ownership still apply.

This is shared foreground handling, with no Steam name or window-title match. It covers direct events, foreground recovery, menu correlation and OCR's process check. It does not establish compatibility with every Flatpak, native Wayland focus, or application-specific scripts behind a proxy. Missing or unreadable instance metadata does not relax matching. The reported Steam 2x2 auxiliary frames remain subject to the ordinary geometry checks.

XRes adds the libxres Arch dependency (xres pkg-config module). Debug logs record both the resolved X11 PID and original property PID.

The Xorg owner caches one client's lookup until the window or property changes. The AT-SPI GLib owner bounds provider comparisons to 128 entries and clears them when the foreground window, process or known state changes. Metadata reads are limited to regular files of at most 64 KiB. No process scan or service manager is used.

References: AT-SPI process query, proxy credentials, Flatpak instance metadata, libwnck's XRes namespace correction.

Automated checks

Run the private fixtures sequentially. The GTK mismatch test fails before the XRes change. The proxy fixture uses real bubblewrap mount namespaces and xdg-dbus-proxy, with synthetic instance metadata; it needs neither an installed Flatpak nor a running desktop reader.

CTHULHU_FOREGROUND_PID=1 python3 tests/native_atspi.py
CTHULHU_FOREGROUND_PID=1 CTHULHU_FOREGROUND_PROXY=1 python3 tests/native_atspi.py
CTHULHU_FOREGROUND_PID=1 CTHULHU_FOREGROUND_PROXY=1 CTHULHU_FOREGROUND_PROXY_OTHER=1 python3 tests/native_atspi.py
xvfb-run -a env CTHULHU_NATIVE_WINDOW_TITLES=1 go test ./internal/platform/xorg -run '^TestNativeWindowTitleDiscovery$' -count=1
xvfb-run -a -s '-screen 0 1280x1024x24 -extension X-Resource' env CTHULHU_NATIVE_WINDOW_TITLES=1 CTHULHU_XRES_DISABLED=1 go test ./internal/platform/xorg -run '^TestNativeWindowTitleDiscovery$' -count=1

The final proxy case must reject the control from a different instance of the same application. Xorg tests cover cached reads, property changes, empty workspaces, destroyed windows and fallback without XRes. Also run the affected Go packages and tests/native_ownership.py with CTHULHU_BINARY pointing to a fresh isolated build; that checks GTK, Qt and Brave foreground boundaries.

Live acceptance

Actual Flatpak Steam, audible speech and physical Braille remain unverified. On the maintainer's i3 setup:

1. Quit Cthulhu with Cthulhu+Q. Press Ctrl+Escape, then Shift+G as separate key presses. Shift+G runs ~/devel/cthulhu-go.sh and rebuilds both binaries.
2. Launch flatpak --user run com.valvesoftware.Steam -tenfoot. Press Tab and Shift+Tab through controls. Each focus move should announce the control label and role; a working Braille display should follow that same control.
3. Open and close a Steam menu with Escape, navigate with arrows and Enter, then type in search. Keys should reach Steam and speech should track the selected control or edited text.
4. Switch to another application's window and back. Steam's ordinary control events should not interrupt the other application; returning should restore announcements. Repeat with another available Flatpak and a native browser.
5. Report the exact spoken text, Braille text if connected, focused control and key that differed from expectation. Preserve ~/devel/cthulhu-go.log after an unexpected result. A remote tester should use their own equivalent rebuild and debug-log launcher; the i3 bindings above are local customizations.

The original report also contains independent Braille geometry errors. This foreground change does not repair the Braille helper's connection failure.