fix(cua-driver): scope the Linux AT-SPI walk to the requested window

[f-trycua]

The bug

The Linux AT-SPI walker took an xid and never used it to scope anything.

atspi/mod.rs::walk_tree(pid, xid, …) → native::walk_tree_bounded(pid, xid, …) → walk_tree_bounded_with_timeout(pid, xid, …), whose body called collect_visited_bounded(conn, pid, max_elements, max_depth). The xid reached only the geometry pass and the degraded X11-property fallback. The traversal itself seeded from every child of the application accessible.

AT-SPI publishes one tree per process, so this meant every "window-scoped" snapshot on Linux was really application-scoped. For a single-window app the two coincide and nothing looks wrong. For a browser — three windows under one PID is an ordinary Tuesday — get_window_state(pid, window_id) returned all of them, and matching a control by label could find one in a window the caller never named.

Why it surfaced now

Existing-profile browser setup drives Chromium's internal chrome://inspect/#remote-debugging page through accessibility: find the checkbox labelled "Allow remote debugging for this browser instance", toggle it, prove the new loopback endpoint, close the temp tab. With an application-wide tree and several windows open, that label match is not guaranteed to be the window the caller approved — and there can be one such checkbox per open setup page.

setup_existing_profile_endpoint guarded against that with a cardinality check:

if self.is_only_exact_native_window(request.pid, request.window_id).await? != Some(true) {
    return Err(refusal(
        BrowserRefusalCode::BrowserBindingAmbiguous,
        "existing-profile setup on Linux requires exactly one PID-owned native window; \
         generic Wayland and multi-window processes are refused",
    ));
}

Sound, but it made the route unreachable for most real sessions: a second Chrome window of any kind fails it. macOS carries no equivalent precondition (platform-macos/src/browser/platform.rs) because AXUIElement is genuinely window-scoped there — a good sign this was a workaround for the missing primitive rather than a principle.

The fix

Resolve the native window to exactly one application top-level, then scope the walk to it.

• resolve_window_frame correlates each frame-role top-level's Component.GetExtents(Screen) against the X11 geometry the caller already named. It runs against the same get_children() list the walk is about to seed from — re-reading it could observe a different window set, and an ordinal resolved against one list but applied to another names the wrong window.
• correlate_frame_to_window scores by geometry distance and requires the winner to be within a tolerance and to beat the runner-up by a margin. Decoration offsets resolve; two same-geometry windows refuse rather than coin-flip.
• Every Visited node carries the frame_ordinal it descends from, inherited by children.
• browser_setup_ui now requires that proof before it matches or actuates any control, and the cardinality precondition is gone. Where window identity genuinely cannot be established — a generic Wayland session with no compositor window list — the same proof fails and setup still refuses, with a message that names the cause and points at --remote-debugging-port.

Element indices stay application-wide

This is the load-bearing detail. Indices are the contract between a snapshot and every actuator that later consumes one — perform_action, focus_element, set_value, scroll_element, type_into_editable_at — and each of those resolves an index against the whole application via collect_visited(conn, pid). Renumbering per window would make a window-scoped snapshot's indices name different elements at actuation time, silently actuating the wrong control.

So render gained an only_frame filter that still consumes the index for skipped nodes and only suppresses emission. A window-scoped snapshot shows one window's nodes carrying their application-wide indices, and actuation keeps resolving them correctly with no changes to any actuator.

Verification

Unit — 7 correlation cases (sibling match, decoration offset, ambiguous tie, no match, no candidates, unmapped zero-area extents, sole-candidate-still-has-to-match). Full platform-linux lib suite: 227 passed.

Live, X11, three-window Chrome under one PID:

window	before	after
52428859 "Sign in – Google Accounts"	all 3 frames	[0] frame "…Your Chrome"
52429004 "hello – Google Search"	all 3 frames	[1] frame "…Francesco 2"
52429010 "Cua: Scale computer fleets…"	all 3 frames	[2] frame "…Francesco 1"

Each window returns only its own frame, with application-wide indices preserved. browser_prepare with strategy=existing_profile no longer refuses on cardinality and proceeds to drive the setup UI.

Live, two-window GTK process (one Mousepad PID, editor + dialog):

• dialog window → 2 elements, indices [0] "No", [1] "Yes"
• editor window → 257 elements, starting at index [2]

Before this change both calls returned all 259 nodes. Then click by element_token minted from the window-scoped dialog snapshot dismissed the dialog — confirming actuation still lands on the right element through the app-wide index space.

Not fixed here

Existing-profile setup still cannot complete against this Chrome instance, for a separate and pre-existing reason: Chrome publishes no renderer content to AT-SPI at all (every window walks to a bare frame with zero children), so the setup page's controls never appear. That is the condition setup_not_ready_message already documents — Chromium needs --force-renderer-accessibility, or an AT client that enables full renderer accessibility. Unrelated to window scoping, and it reproduces identically on windows the setup flow never touched.

Cross-platform e2e coverage for these browser paths, including non-active tabs and multi-window PIDs, is tracked in #2892.

Refs #2892

🤖 Generated with Claude Code

https://claude.ai/code/session_017zpeGjLTLSALtHsuxKLkNp