Reset master to testing content

docs/testing/flatpak-foreground.md

@@ -0,0 +1,80 @@
+# 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](https://gnome.pages.gitlab.gnome.org/gtk/atspi2/method.Accessible.get_process_id.html),
+[proxy credentials](https://github.com/flatpak/xdg-dbus-proxy/blob/main/xdg-dbus-proxy.xml),
+[Flatpak instance metadata](https://github.com/flatpak/flatpak/blob/main/doc/flatpak-metadata.xml),
+[libwnck's XRes namespace correction](https://lists.gnome.org/archives/commits-list/2022-March/msg10404.html).
+
+## 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.
+
+```sh
+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.