Skip to main content

computer_use_linux/
atspi_tree.rs

1use crate::diagnostics::hydrate_session_bus_env;
2use anyhow::{anyhow, Context, Result};
3use atspi::{
4    proxy::{
5        accessible::{AccessibleProxy, ObjectRefExt},
6        action::ActionProxy,
7        editable_text::EditableTextProxy,
8        proxy_ext::{Proxies, ProxyExt},
9        text::TextProxy,
10    },
11    CoordType, ObjectRef, ObjectRefOwned, StateSet,
12};
13// Direct dependency (p2p feature off) — see Cargo.toml for why we bypass
14// atspi's "connection" re-export.
15use atspi_connection::AccessibilityConnection;
16use futures_util::{stream, StreamExt};
17use schemars::JsonSchema;
18use serde::Serialize;
19use std::{collections::VecDeque, future::Future, time::Duration};
20use tokio::time::{sleep_until, timeout, timeout_at, Instant};
21use zbus::{
22    fdo::DBusProxy,
23    names::{BusName, UniqueName},
24    zvariant::{ObjectPath, OwnedObjectPath},
25};
26
27#[derive(Debug, Clone, Serialize, JsonSchema)]
28pub struct AccessibleAppSummary {
29    pub object_ref: String,
30    pub name: Option<String>,
31    pub pid: Option<u32>,
32    pub role: String,
33    pub child_count: i32,
34    pub bounds: Option<Bounds>,
35}
36
37#[derive(Debug, Clone, Serialize, JsonSchema)]
38pub struct AccessibilityNode {
39    pub index: u32,
40    pub parent_index: Option<u32>,
41    pub depth: u32,
42    pub object_ref: String,
43    pub role: String,
44    pub name: Option<String>,
45    pub description: Option<String>,
46    pub child_count: i32,
47    pub bounds: Option<Bounds>,
48    pub states: Vec<String>,
49    pub actions: Vec<AccessibilityAction>,
50    pub value: Option<AccessibilityValue>,
51    pub text: Option<AccessibilityText>,
52    pub supports_editable_text: bool,
53}
54
55#[derive(Debug, Clone, Serialize, JsonSchema)]
56pub struct Bounds {
57    pub x: i32,
58    pub y: i32,
59    pub width: i32,
60    pub height: i32,
61}
62
63#[derive(Debug, Clone, Serialize, JsonSchema)]
64pub struct AccessibilityAction {
65    pub index: i32,
66    pub name: String,
67    pub description: String,
68    pub keybinding: String,
69}
70
71#[derive(Debug, Clone, Serialize, JsonSchema)]
72pub struct AccessibilityValue {
73    pub current: f64,
74    pub minimum: f64,
75    pub maximum: f64,
76    pub minimum_increment: f64,
77    pub text: Option<String>,
78}
79
80#[derive(Debug, Clone, Serialize, JsonSchema)]
81pub struct AccessibilityText {
82    pub character_count: i32,
83    pub caret_offset: Option<i32>,
84    pub content: Option<String>,
85    pub truncated: bool,
86    pub selections: Vec<AccessibilityTextSelection>,
87}
88
89#[derive(Debug, Clone, Serialize, JsonSchema)]
90pub struct AccessibilityTextSelection {
91    pub start_offset: i32,
92    pub end_offset: i32,
93}
94
95#[derive(Debug, Clone)]
96pub struct ActionInvocation {
97    pub action_index: i32,
98    pub action_name: Option<String>,
99    pub ok: bool,
100}
101
102#[derive(Debug, Clone)]
103pub enum ValueSetInvocation {
104    Numeric { value: f64 },
105    EditableText { outcome: EditableTextSetOutcome },
106}
107
108#[derive(Debug, Clone, Copy, PartialEq, Eq)]
109pub enum EditableTextSetOutcome {
110    Verified,
111    MismatchAfterDeadline,
112    ReadbackFailed,
113    ReadbackTimedOut,
114    PasswordUnverifiable,
115}
116
117const MAX_TEXT_READBACK_CHARS: i32 = 4096;
118const EDITABLE_TEXT_READ_CHUNK_UNITS: usize = 4096;
119const EDITABLE_TEXT_VERIFY_TIMEOUT: Duration = Duration::from_secs(1);
120const EDITABLE_TEXT_VERIFY_INTERVAL: Duration = Duration::from_millis(50);
121const MAX_TEXT_SELECTIONS: i32 = 8;
122const DEFAULT_SNAPSHOT_MAX_NODES: usize = 1_000;
123// Larger trees are opt-in; the default and the 10-second deadline stay unchanged.
124const HARD_SNAPSHOT_MAX_NODES: usize = 10_000;
125const DEFAULT_SNAPSHOT_MAX_DEPTH: u32 = 32;
126const HARD_SNAPSHOT_MAX_DEPTH: u32 = 64;
127const CHILD_READ_CONCURRENCY: usize = 16;
128const SNAPSHOT_TIMEOUT: Duration = Duration::from_secs(10);
129/// Time past `SNAPSHOT_TIMEOUT` for the node being read to finish; a node still
130/// reading after it is dropped and the tree is returned truncated.
131const SNAPSHOT_HARD_GRACE: Duration = Duration::from_secs(2);
132const MAX_ACTIONS_PER_OBJECT: i32 = 64;
133const ACTION_QUERY_TIMEOUT: Duration = Duration::from_secs(5);
134const MAX_DISCOVERY_ROOTS: usize = 256;
135const ROOT_MATCH_CHILD_LIMIT: usize = 8;
136const MAX_DISCOVERY_CHILD_READS: usize = MAX_DISCOVERY_ROOTS * ROOT_MATCH_CHILD_LIMIT;
137
138fn snapshot_child_read_budgets(max_nodes: usize) -> (usize, usize, usize) {
139    (MAX_DISCOVERY_ROOTS, MAX_DISCOVERY_CHILD_READS, max_nodes)
140}
141
142pub(crate) fn snapshot_limits(
143    requested_max_nodes: Option<usize>,
144    requested_max_depth: Option<u32>,
145) -> (usize, u32) {
146    (
147        requested_max_nodes
148            .unwrap_or(DEFAULT_SNAPSHOT_MAX_NODES)
149            .clamp(1, HARD_SNAPSHOT_MAX_NODES),
150        requested_max_depth
151            .unwrap_or(DEFAULT_SNAPSHOT_MAX_DEPTH)
152            .min(HARD_SNAPSHOT_MAX_DEPTH),
153    )
154}
155
156struct BoundedTraversal<T> {
157    queue: VecDeque<T>,
158    attempted: usize,
159    max_items: usize,
160    /// Set once an enqueue had to drop offered items for lack of capacity.
161    dropped: bool,
162}
163
164impl<T> BoundedTraversal<T> {
165    fn new(max_items: usize) -> Self {
166        Self {
167            queue: VecDeque::new(),
168            attempted: 0,
169            max_items,
170            dropped: false,
171        }
172    }
173
174    fn enqueue(&mut self, items: impl IntoIterator<Item = T>) {
175        let capacity = self.remaining_capacity();
176        let mut items = items.into_iter();
177        self.queue.extend(items.by_ref().take(capacity));
178        if items.next().is_some() {
179            self.dropped = true;
180        }
181    }
182
183    fn pop(&mut self) -> Option<T> {
184        if self.attempted >= self.max_items {
185            return None;
186        }
187        let item = self.queue.pop_front()?;
188        self.attempted += 1;
189        Some(item)
190    }
191
192    fn remaining_capacity(&self) -> usize {
193        self.max_items
194            .saturating_sub(self.attempted.saturating_add(self.queue.len()))
195    }
196
197    /// Drop pending and earlier dropped work, keeping the spent budget, so the
198    /// rest of the budget goes to the subtree enqueued next.
199    fn narrow(&mut self) {
200        self.queue.clear();
201        self.dropped = false;
202    }
203
204    /// True when the budget stopped work that was actually offered. `enqueue`
205    /// is the only gate: it never exceeds `remaining_capacity`, so
206    /// `attempted + queue.len() <= max_items` always holds and the queue can
207    /// never be non-empty at the attempt cap. Dropped items are the whole story.
208    fn truncated(&self) -> bool {
209        self.dropped
210    }
211}
212
213fn bounded_child_count(reported: i32, limit: usize) -> usize {
214    usize::try_from(reported).unwrap_or_default().min(limit)
215}
216
217struct IndexedReadBatch<T> {
218    items: Vec<T>,
219    attempted: usize,
220    /// True when fewer children were attempted than the parent reported, because
221    /// the caller's limit or the shared read budget ran out. Failed reads do not
222    /// count; they were attempted.
223    incomplete: bool,
224}
225
226impl<T> IndexedReadBatch<T> {
227    fn all_failed(&self) -> bool {
228        self.attempted > 0 && self.items.is_empty()
229    }
230}
231
232async fn fetch_indexed_up_to<T, E, F, Fut>(
233    reported: i32,
234    limit: usize,
235    remaining_attempts: &mut usize,
236    fetch: F,
237) -> IndexedReadBatch<T>
238where
239    F: Fn(i32) -> Fut,
240    Fut: Future<Output = std::result::Result<T, E>>,
241{
242    let attempt_count = bounded_child_count(reported, limit).min(*remaining_attempts);
243    *remaining_attempts = (*remaining_attempts).saturating_sub(attempt_count);
244    let end_index = i32::try_from(attempt_count).unwrap_or(i32::MAX);
245
246    let items = stream::iter(0..end_index)
247        .map(fetch)
248        .buffered(CHILD_READ_CONCURRENCY)
249        .filter_map(|result| async move { result.ok() })
250        .collect()
251        .await;
252
253    IndexedReadBatch {
254        items,
255        attempted: attempt_count,
256        incomplete: attempt_count < usize::try_from(reported).unwrap_or_default(),
257    }
258}
259
260async fn children_up_to(
261    proxy: &AccessibleProxy<'_>,
262    limit: usize,
263    remaining_attempts: &mut usize,
264) -> zbus::Result<IndexedReadBatch<ObjectRefOwned>> {
265    if limit == 0 || *remaining_attempts == 0 {
266        // Budget already spent: stay I/O-free. `incomplete` is false here because
267        // nothing was asked of the parent; callers that already hold the node's
268        // child_count (snapshot_tree_inner) derive truncation from that instead.
269        return Ok(IndexedReadBatch {
270            items: Vec::new(),
271            attempted: 0,
272            incomplete: false,
273        });
274    }
275
276    let child_count = proxy.child_count().await?;
277    Ok(
278        fetch_indexed_up_to(child_count, limit, remaining_attempts, |index| {
279            child_at_index(proxy, index)
280        })
281        .await,
282    )
283}
284
285async fn child_at_index(proxy: &AccessibleProxy<'_>, index: i32) -> zbus::Result<ObjectRefOwned> {
286    // WebKit sockets return a well-known bus name. atspi's ObjectRef decoder
287    // only accepts unique names, so resolve the wire reference before using it.
288    let (name, path): (String, OwnedObjectPath) =
289        proxy.inner().call("GetChildAtIndex", &(index,)).await?;
290    if path.as_str() == "/org/a11y/atspi/null" {
291        return Ok(ObjectRef::Null.into());
292    }
293    match BusName::try_from(name)? {
294        BusName::Unique(name) => Ok(ObjectRef::new_owned(name, path)),
295        name => {
296            let owner = DBusProxy::new(proxy.inner().connection())
297                .await?
298                .get_name_owner(name)
299                .await?;
300            Ok(ObjectRef::new_owned(owner, path))
301        }
302    }
303}
304
305pub async fn list_accessible_apps(limit: usize) -> Result<Vec<AccessibleAppSummary>> {
306    let conn = connect().await?;
307    let mut remaining_child_reads = limit;
308    let roots = registry_children(&conn, limit, &mut remaining_child_reads).await?;
309    let dbus = DBusProxy::new(conn.connection()).await.ok();
310    let mut apps = Vec::new();
311
312    for object_ref in roots.into_iter().take(limit) {
313        if let Ok(proxy) = open_accessible(&conn, &object_ref).await {
314            apps.push(read_app_summary(&proxy, &object_ref, dbus.as_ref()).await);
315        }
316    }
317
318    Ok(apps)
319}
320
321#[derive(Debug, Clone)]
322pub(crate) struct AccessibilitySnapshot {
323    pub nodes: Vec<AccessibilityNode>,
324    /// True when registry roots were filtered to an app name and/or pid.
325    pub scoped: bool,
326    /// The pid every root belongs to, when roots were matched by pid. None
327    /// when they were matched by app name alone or not filtered at all: those
328    /// roots can belong to any app, so no single pid describes the tree.
329    pub root_pid: Option<u32>,
330    /// True when selected roots satisfy the supplied app/name filter, or no
331    /// filter was supplied. Normal snapshots retain their PID-only fallback;
332    /// action recovery requires this evidence before invoking a fresh node.
333    pub app_filter_matched: bool,
334    /// True when max_nodes, max_depth, the child read budget, or the deadline stopped
335    /// traversal with unread elements left. Failed element reads do not count.
336    pub truncated: bool,
337    /// Name of the AT-SPI window the tree was narrowed to, when an app root
338    /// exposed several windows and exactly one matched the window title.
339    pub window_scope: Option<String>,
340}
341
342pub async fn snapshot_tree(
343    app_name_or_bundle_identifier: Option<&str>,
344    target_pid: Option<u32>,
345    max_nodes: usize,
346    max_depth: u32,
347) -> Result<Vec<AccessibilityNode>> {
348    Ok(snapshot_accessibility_tree(
349        app_name_or_bundle_identifier,
350        target_pid,
351        None,
352        None,
353        max_nodes,
354        max_depth,
355    )
356    .await?
357    .nodes)
358}
359
360/// Read the accessibility tree of the matching app roots. With
361/// `window_title`, an app root that exposes several windows (Chromium puts
362/// every browser window under one application) is read only through the
363/// window whose name matches it; its other children stay.
364/// `pid_fallback_name` finds the roots by name when `target_pid` owns none;
365/// pass it only for a pid read from a window the compositor listed.
366pub(crate) async fn snapshot_accessibility_tree(
367    app_name_or_bundle_identifier: Option<&str>,
368    target_pid: Option<u32>,
369    window_title: Option<&str>,
370    pid_fallback_name: Option<&str>,
371    max_nodes: usize,
372    max_depth: u32,
373) -> Result<AccessibilitySnapshot> {
374    let (max_nodes, max_depth) = snapshot_limits(Some(max_nodes), Some(max_depth));
375    // Traversal stops at the deadline and returns what it read, marked truncated.
376    // The outer timeout only bounds app discovery, which runs before any node
377    // is read; the traversal itself ends by `stop_reading` plus the grace.
378    let stop_reading = Instant::now() + SNAPSHOT_TIMEOUT;
379    timeout(
380        SNAPSHOT_TIMEOUT + SNAPSHOT_HARD_GRACE + SNAPSHOT_HARD_GRACE,
381        snapshot_tree_inner(
382            app_name_or_bundle_identifier,
383            target_pid,
384            window_title
385                .map(str::trim)
386                .filter(|title| !title.is_empty()),
387            pid_fallback_name,
388            max_nodes,
389            max_depth,
390            stop_reading,
391        ),
392    )
393    .await
394    .context("AT-SPI snapshot could not find its target before the deadline")?
395}
396
397async fn snapshot_tree_inner(
398    app_name_or_bundle_identifier: Option<&str>,
399    target_pid: Option<u32>,
400    window_title: Option<&str>,
401    pid_fallback_name: Option<&str>,
402    max_nodes: usize,
403    max_depth: u32,
404    stop_reading: Instant,
405) -> Result<AccessibilitySnapshot> {
406    let conn = connect().await?;
407    // App discovery is bounded independently so a tiny requested tree still
408    // finds a target registered after the first accessibility root.
409    let (mut remaining_registry_reads, mut remaining_filter_reads, mut remaining_traversal_reads) =
410        snapshot_child_read_budgets(max_nodes);
411    let roots =
412        registry_children(&conn, MAX_DISCOVERY_ROOTS, &mut remaining_registry_reads).await?;
413    let selected_roots = select_roots(
414        &conn,
415        roots,
416        app_name_or_bundle_identifier,
417        target_pid,
418        pid_fallback_name,
419        &mut remaining_filter_reads,
420    )
421    .await;
422    let scoped = selected_roots.scoped;
423    let root_pid = selected_roots.pid;
424    let app_filter_matched = selected_roots.app_filter_matched;
425    let mut nodes = Vec::new();
426    let mut truncated = false;
427    let mut window_scope = None;
428    let mut traversal = BoundedTraversal::new(max_nodes);
429
430    traversal.enqueue(
431        selected_roots
432            .roots
433            .into_iter()
434            .map(|object_ref| (object_ref, 0_u32, None)),
435    );
436
437    // Each node's reads may run past `stop_reading` by the grace, never more: a
438    // slow action query (up to ACTION_QUERY_TIMEOUT) near the deadline cuts the
439    // tree there instead of losing it to the outer timeout.
440    let node_cutoff = stop_reading + SNAPSHOT_HARD_GRACE;
441    while let Some((object_ref, depth, parent_index)) = traversal.pop() {
442        if Instant::now() >= stop_reading {
443            truncated = true;
444            break;
445        }
446        let index = nodes.len() as u32;
447        let remaining = traversal.remaining_capacity();
448        let read = timeout_at(node_cutoff, async {
449            let Ok(proxy) = open_accessible(&conn, &object_ref).await else {
450                return None;
451            };
452            let node = read_node(&proxy, &object_ref, index, parent_index, depth).await;
453            let mut cut = false;
454            let mut scope = None;
455            let child_refs = if depth < max_depth && remaining > 0 {
456                match children_up_to(&proxy, remaining, &mut remaining_traversal_reads).await {
457                    Ok(batch) => {
458                        // A read-budget cut inside the fetch reports `incomplete`; an
459                        // already-exhausted budget returns the I/O-free empty batch, so
460                        // fall back to the child_count read_node already fetched.
461                        cut = batch.incomplete || (batch.attempted == 0 && node.child_count > 0);
462                        match window_title.filter(|_| depth == 0) {
463                            Some(title) => {
464                                let (children, matched) =
465                                    scope_to_window(&conn, batch.items, title).await;
466                                scope = matched;
467                                children
468                            }
469                            None => batch.items,
470                        }
471                    }
472                    Err(_) => Vec::new(),
473                }
474            } else {
475                // Depth or node cap reached: any child this node reports is unread.
476                cut = node.child_count > 0;
477                Vec::new()
478            };
479            Some((node, child_refs, cut, scope))
480        })
481        .await;
482        let Ok(read) = read else {
483            truncated = true;
484            break;
485        };
486        let Some((node, child_refs, cut, scope)) = read else {
487            continue;
488        };
489        truncated |= cut;
490        if scope.is_some() {
491            window_scope = scope;
492        }
493        nodes.push(node);
494
495        traversal.enqueue(
496            child_refs
497                .into_iter()
498                .map(|child| (child, depth + 1, Some(index))),
499        );
500    }
501    truncated |= traversal.truncated();
502
503    Ok(AccessibilitySnapshot {
504        nodes,
505        scoped,
506        root_pid,
507        app_filter_matched,
508        truncated,
509        window_scope,
510    })
511}
512
513/// Children of an app root, narrowed to the window named `title` when the root
514/// holds several windows. Returns the children to read and the matched window
515/// name. Only the other named frames are dropped: popups, menus, dialogs and
516/// unnamed windows are kept, since Chromium puts a window's popups and dialogs
517/// beside it under the app root.
518async fn scope_to_window(
519    conn: &AccessibilityConnection,
520    children: Vec<ObjectRefOwned>,
521    title: &str,
522) -> (Vec<ObjectRefOwned>, Option<String>) {
523    // An app root has a handful of windows; read them in order.
524    let mut labels = Vec::with_capacity(children.len());
525    for child in &children {
526        labels.push(match open_accessible(conn, child).await {
527            Ok(proxy) => (
528                role_name(&proxy).await,
529                optional_string(proxy.name().await.ok()),
530            ),
531            Err(_) => (String::new(), None),
532        });
533    }
534    let Some(chosen) = matching_window(&labels, title) else {
535        return (children, None);
536    };
537    let name = labels[chosen].1.clone();
538    let keep = kept_beside_window(&labels, chosen);
539    let kept = children
540        .into_iter()
541        .zip(keep)
542        .filter_map(|(child, keep)| keep.then_some(child))
543        .collect();
544    (kept, name)
545}
546
547/// Which app root children (`(role, name)`) stay when `chosen` is the targeted
548/// window: it, and every child that is not another named frame.
549fn kept_beside_window(children: &[(String, Option<String>)], chosen: usize) -> Vec<bool> {
550    children
551        .iter()
552        .enumerate()
553        .map(|(index, (role, name))| {
554            index == chosen
555                || role != "frame"
556                || name.as_deref().is_none_or(|name| name.trim().is_empty())
557        })
558        .collect()
559}
560
561pub(crate) fn is_window_role(role: &str) -> bool {
562    matches!(role, "frame" | "window" | "dialog" | "file chooser")
563}
564
565/// Index of the one window among an app root's children (`(role, name)`)
566/// that `title` names, when the root has at least two windows. An exact name
567/// wins, then a case-insensitive one, then the one name that contains
568/// `title`, ignoring case. A tie at the first rule that matches returns
569/// `None`, which keeps every window. With no match at all, the longest name
570/// that `title` starts with, followed by a decoration (` (...)` or
571/// ` - ...`), wins: a compositor title such as Chromium's
572/// "PlanetScale - Chromium (Profile 1)" decorates the AT-SPI frame name
573/// "PlanetScale - Chromium".
574fn matching_window(children: &[(String, Option<String>)], title: &str) -> Option<usize> {
575    let windows: Vec<(usize, &str)> = children
576        .iter()
577        .enumerate()
578        .filter(|(_, (role, _))| is_window_role(role))
579        .map(|(index, (_, name))| (index, name.as_deref().unwrap_or_default().trim()))
580        .collect();
581    if windows.len() < 2 {
582        return None;
583    }
584    let title = title.trim();
585    let lowered = title.to_lowercase();
586    let rules: [&dyn Fn(&str) -> bool; 3] = [
587        &|name| name == title,
588        &|name| name.to_lowercase() == lowered,
589        &|name| name.to_lowercase().contains(&lowered),
590    ];
591    for rule in rules {
592        let mut matches = windows.iter().filter(|(_, name)| rule(name));
593        if let Some((index, _)) = matches.next() {
594            return matches.next().is_none().then_some(*index);
595        }
596    }
597    let decorated = |name: &str| {
598        let name = name.to_lowercase();
599        !name.is_empty()
600            && lowered.strip_prefix(&name).is_some_and(|rest| {
601                rest.starts_with(" (") || rest.starts_with(" - ") || rest.starts_with(" \u{2014} ")
602            })
603    };
604    let decorated_matches = windows.iter().filter(|(_, name)| decorated(name));
605    let longest = decorated_matches
606        .clone()
607        .map(|(_, name)| name.len())
608        .max()?;
609    let mut longest_matches = decorated_matches.filter(|(_, name)| name.len() == longest);
610    let (index, _) = longest_matches.next()?;
611    longest_matches.next().is_none().then_some(*index)
612}
613
614/// Compact description of the AT-SPI element that currently holds keyboard
615/// focus, used as post-input feedback for type_text/press_key.
616#[derive(Debug, Clone, Serialize, JsonSchema)]
617pub struct FocusedElementSummary {
618    pub role: String,
619    pub name: Option<String>,
620    pub editable: bool,
621    pub states: Vec<String>,
622    /// AT-SPI `Role::Terminal`, read from the role enum rather than the
623    /// localized role name. Internal routing only; not part of the output.
624    #[serde(skip)]
625    #[schemars(skip)]
626    pub is_terminal: bool,
627}
628
629impl FocusedElementSummary {
630    /// A field that takes typed text: editable, or a text-entry role.
631    pub(crate) fn accepts_text(&self) -> bool {
632        self.editable
633            || self.states.iter().any(|state| state == "editable")
634            || matches!(
635                self.role.as_str(),
636                "text" | "entry" | "password text" | "combo box"
637            )
638    }
639}
640
641const FOCUS_PROBE_MAX_NODES: usize = 400;
642const FOCUS_PROBE_MAX_DEPTH: u32 = 16;
643
644/// Find the element with the `focused` state inside the target app (by pid) or
645/// across all apps. Best-effort and bounded: returns Ok(None) when no focused
646/// element is reachable through AT-SPI (common for apps without accessibility
647/// support, e.g. Electron without --force-renderer-accessibility).
648/// Outcome of the bounded focused-element search.
649#[derive(Debug, Clone)]
650pub(crate) enum FocusProbe {
651    Found(FocusedElementSummary),
652    /// The search covered the target's whole tree and nothing holds focus.
653    NoneFocused,
654    /// A complete scoped search saw only window/menu chrome, no content.
655    ShellOnly,
656    /// A node, depth, or read limit stopped the search before it finished, so
657    /// the focused element may exist past the limit.
658    Incomplete,
659    /// A pid was given but no AT-SPI app belongs to it (xterm, or Electron
660    /// without --force-renderer-accessibility), so focus cannot be read.
661    NoAccessibleApp,
662}
663
664/// Focused element in the app owning `target_pid`, or across all apps when no
665/// pid is given. With a pid, only that app's tree is searched: falling back to
666/// every other app would report some unrelated widget as the focus.
667pub(crate) async fn probe_focused_element(target_pid: Option<u32>) -> Result<FocusProbe> {
668    focused_element_probe(target_pid, target_pid.is_some()).await
669}
670
671/// The focused element in the app that owns `target_pid`, for callers that
672/// only need an answer when one exists. Every non-`Found` probe result maps to
673/// `None`; see [`probe_focused_element`] for the distinctions.
674pub(crate) async fn focused_element_summary_in_app(
675    target_pid: u32,
676) -> Result<Option<FocusedElementSummary>> {
677    Ok(match focused_element_probe(Some(target_pid), true).await? {
678        FocusProbe::Found(summary) => Some(summary),
679        _ => None,
680    })
681}
682
683async fn focused_element_probe(
684    target_pid: Option<u32>,
685    require_scoped: bool,
686) -> Result<FocusProbe> {
687    let conn = connect().await?;
688    Ok(focused_element_search(&conn, target_pid, require_scoped)
689        .await?
690        .0)
691}
692
693/// The bounded focus search. A `Found` result for a non-container element
694/// also returns that element's reference.
695async fn focused_element_search(
696    conn: &AccessibilityConnection,
697    target_pid: Option<u32>,
698    require_scoped: bool,
699) -> Result<(FocusProbe, Option<ObjectRefOwned>)> {
700    let mut remaining_registry_reads = MAX_DISCOVERY_ROOTS;
701    let roots = registry_children(conn, MAX_DISCOVERY_ROOTS, &mut remaining_registry_reads).await?;
702    let mut remaining_filter_reads = MAX_DISCOVERY_CHILD_READS;
703    let selected_roots = select_roots(
704        conn,
705        roots,
706        None,
707        target_pid,
708        None,
709        &mut remaining_filter_reads,
710    )
711    .await;
712    if require_scoped && selected_roots.pid != target_pid {
713        return Ok((FocusProbe::NoAccessibleApp, None));
714    }
715    focused_element_search_from(conn, selected_roots.roots, require_scoped).await
716}
717
718/// The focus search below `roots`.
719async fn focused_element_search_from(
720    conn: &AccessibilityConnection,
721    roots: Vec<ObjectRefOwned>,
722    require_scoped: bool,
723) -> Result<(FocusProbe, Option<ObjectRefOwned>)> {
724    let mut traversal = BoundedTraversal::new(FOCUS_PROBE_MAX_NODES);
725    let mut remaining_traversal_reads = FOCUS_PROBE_MAX_NODES;
726    let mut incomplete = false;
727    let mut shell_only = true;
728    let mut observed_nodes = 0;
729    let mut focused_container = None;
730    let mut depth_base = 0_u32;
731
732    traversal.enqueue(
733        roots
734            .into_iter()
735            .map(|object_ref| (object_ref, 0_u32, false)),
736    );
737
738    while let Some((object_ref, depth, in_menu)) = traversal.pop() {
739        let Ok(proxy) = open_accessible(conn, &object_ref).await else {
740            incomplete = true;
741            continue;
742        };
743        let Ok(state) = proxy.get_state().await else {
744            incomplete = true;
745            continue;
746        };
747        observed_nodes += 1;
748        let mut child_menu = false;
749        if shell_only {
750            match accessibility_chrome_context(&role_name(&proxy).await, in_menu) {
751                Some(menu) => child_menu = menu,
752                None => shell_only = false,
753            }
754        }
755        if state.contains(atspi::State::Focused) {
756            let proxies = proxy.proxies().await.ok();
757            let is_terminal = matches!(proxy.get_role().await, Ok(atspi::Role::Terminal));
758            let summary = FocusedElementSummary {
759                role: role_name(&proxy).await,
760                name: optional_string(proxy.name().await.ok()),
761                editable: supports_editable_text(proxies.as_ref()).await,
762                states: state_labels(state),
763                is_terminal,
764            };
765            // Chromium can mark both a document and its contenteditable entry
766            // focused. Do not stop at the ancestor before visiting the editor:
767            // the focus is inside it, so the rest of the budget searches only
768            // its subtree, and nodes left unread elsewhere no longer matter.
769            if focus_is_container(&summary) {
770                focused_container = Some(summary);
771                // Only within one app: across apps a stale focused document in
772                // another app must not hide the real focus.
773                if require_scoped {
774                    traversal.narrow();
775                    // The discarded queue had spent its child reads; the subtree
776                    // gets the rest of the node budget, and its depth counts from
777                    // the container.
778                    remaining_traversal_reads = traversal.remaining_capacity();
779                    depth_base = depth;
780                    incomplete = false;
781                }
782            } else {
783                return Ok((FocusProbe::Found(summary), Some(object_ref.clone())));
784            }
785        }
786        let remaining = traversal.remaining_capacity();
787        if depth - depth_base < FOCUS_PROBE_MAX_DEPTH && remaining > 0 {
788            if let Ok(batch) =
789                children_up_to(&proxy, remaining, &mut remaining_traversal_reads).await
790            {
791                incomplete |= batch.incomplete;
792                // An exhausted shared read budget takes children_up_to's
793                // I/O-free path (attempted 0, incomplete false), so the node's
794                // own child count has to say whether children went unread.
795                // With budget left, attempted 0 just means a leaf: no read.
796                if batch.attempted == 0 && remaining_traversal_reads == 0 && !incomplete {
797                    incomplete = proxy.child_count().await.map_or(true, |count| count > 0);
798                }
799                traversal.enqueue(
800                    batch
801                        .items
802                        .into_iter()
803                        .map(|child| (child, depth + 1, child_menu)),
804                );
805            } else {
806                incomplete = true;
807            }
808        } else if !incomplete {
809            // Depth or node cap: any child this node reports goes unread. One
810            // child-count read settles it, and only until the first cut is seen.
811            incomplete = proxy.child_count().await.map_or(true, |count| count > 0);
812        }
813    }
814    Ok((
815        finish_focus_probe(
816            incomplete || traversal.truncated(),
817            require_scoped && shell_only && observed_nodes > 0,
818            focused_container,
819        ),
820        None,
821    ))
822}
823
824pub(crate) fn focus_is_container(element: &FocusedElementSummary) -> bool {
825    !element.editable
826        && !element.states.iter().any(|state| state == "editable")
827        && !element.is_terminal
828        && matches!(
829            element.role.as_str(),
830            "application"
831                | "frame"
832                | "window"
833                | "panel"
834                | "filler"
835                | "section"
836                | "document web"
837                | "document frame"
838                | "document text"
839        )
840}
841
842fn finish_focus_probe(
843    incomplete: bool,
844    shell_only: bool,
845    focused_container: Option<FocusedElementSummary>,
846) -> FocusProbe {
847    // A focused container is not a definitive recipient if descendants were
848    // unread. Preserve uncertainty rather than reporting a non-editable field.
849    if incomplete {
850        FocusProbe::Incomplete
851    } else if let Some(container) = focused_container {
852        FocusProbe::Found(container)
853    } else if shell_only {
854        FocusProbe::ShellOnly
855    } else {
856        FocusProbe::NoneFocused
857    }
858}
859
860/// Window and native menu chrome can exist without Electron renderer content.
861/// This is evidence about tree coverage, not positive Electron detection.
862pub(crate) fn accessibility_chrome_context(role: &str, in_menu: bool) -> Option<bool> {
863    match role {
864        "application" | "frame" | "window" | "panel" | "filler" | "separator" => Some(in_menu),
865        "menu bar" | "menu" | "menu item" | "check menu item" | "radio menu item"
866        | "tearoff menu item" => Some(true),
867        // Electron's native menu buttons are exposed as buttons, not menu items.
868        "button" | "push button" | "label" | "static" | "image" | "icon" if in_menu => Some(true),
869        _ => None,
870    }
871}
872
873pub async fn perform_action(
874    object_ref_id: &str,
875    requested_action: Option<&str>,
876) -> Result<ActionInvocation> {
877    perform_action_inner(object_ref_id, requested_action, false).await
878}
879
880pub(crate) async fn perform_named_action(
881    object_ref_id: &str,
882    name: &str,
883) -> Result<ActionInvocation> {
884    perform_action_inner(object_ref_id, Some(name), true).await
885}
886
887async fn perform_action_inner(
888    object_ref_id: &str,
889    requested_action: Option<&str>,
890    name_only: bool,
891) -> Result<ActionInvocation> {
892    let object_ref = object_ref_from_id(object_ref_id)?;
893    let (action, action_index, action_name) = timeout(ACTION_QUERY_TIMEOUT, async {
894        let conn = connect().await?;
895        let proxy = open_accessible(&conn, &object_ref)
896            .await
897            .with_context(|| format!("failed to open AT-SPI object {object_ref_id}"))?;
898        let action = proxy
899            .proxies()
900            .await?
901            .action()
902            .await
903            .context("element does not expose the AT-SPI Action interface")?;
904        let actions = read_actions(&action).await?;
905        let action_index = if name_only {
906            select_named_action_index(&actions, requested_action.unwrap_or_default())?
907        } else {
908            select_action_index(&actions, requested_action)?
909        };
910        let action_name = actions
911            .get(action_index as usize)
912            .map(|action| action.name.clone());
913        Ok::<_, anyhow::Error>((action, action_index, action_name))
914    })
915    .await
916    .context("AT-SPI action revalidation exceeded its 5-second deadline")??;
917    // Only time out the reads: once DoAction is sent, it may already have acted.
918    let ok = action
919        .do_action(action_index)
920        .await
921        .with_context(|| format!("failed to invoke AT-SPI action {action_index}"))?;
922
923    Ok(ActionInvocation {
924        action_index,
925        action_name,
926        ok,
927    })
928}
929
930pub async fn set_element_value(object_ref_id: &str, value: &str) -> Result<ValueSetInvocation> {
931    let conn = connect().await?;
932    let object_ref = object_ref_from_id(object_ref_id)?;
933    let proxy = open_accessible(&conn, &object_ref)
934        .await
935        .with_context(|| format!("failed to open AT-SPI object {object_ref_id}"))?;
936    let proxies = proxy.proxies().await?;
937    set_element_value_with_proxies(&proxy, &proxies, value).await
938}
939
940async fn set_element_value_with_proxies(
941    proxy: &AccessibleProxy<'_>,
942    proxies: &Proxies<'_>,
943    value: &str,
944) -> Result<ValueSetInvocation> {
945    if let Ok(numeric_value) = value.parse::<f64>() {
946        if let Ok(value_proxy) = proxies.value().await {
947            value_proxy
948                .set_current_value(numeric_value)
949                .await
950                .with_context(|| {
951                    format!("failed to set AT-SPI numeric value to {numeric_value}")
952                })?;
953            return Ok(ValueSetInvocation::Numeric {
954                value: numeric_value,
955            });
956        }
957    }
958
959    if let Ok(editable_text) = proxies.editable_text().await {
960        return set_editable_text_contents(proxy, proxies, &editable_text, value).await;
961    }
962
963    if value.parse::<f64>().is_err() && proxies.value().await.is_ok() {
964        return Err(anyhow!(
965            "element exposes the AT-SPI Value interface, but the requested value is not numeric"
966        ));
967    }
968
969    Err(anyhow!(
970        "element does not expose AT-SPI Value or EditableText interfaces"
971    ))
972}
973
974async fn set_editable_text_contents(
975    proxy: &AccessibleProxy<'_>,
976    proxies: &Proxies<'_>,
977    editable_text: &EditableTextProxy<'_>,
978    value: &str,
979) -> Result<ValueSetInvocation> {
980    let ok = editable_text
981        .set_text_contents(value)
982        .await
983        .context("failed to set AT-SPI editable text contents")?;
984    if !ok {
985        return Err(anyhow!("AT-SPI EditableText rejected the new contents"));
986    }
987
988    let outcome = verify_editable_text_contents(proxy, proxies, value).await;
989    Ok(ValueSetInvocation::EditableText { outcome })
990}
991
992#[derive(Debug, Clone, Copy, PartialEq, Eq)]
993enum EditableTextReadbackError {
994    Failed,
995    TimedOut,
996}
997
998async fn readback_within<T, E>(
999    deadline: Instant,
1000    read: impl Future<Output = std::result::Result<T, E>>,
1001) -> std::result::Result<T, EditableTextReadbackError> {
1002    timeout_at(deadline, read)
1003        .await
1004        .map_err(|_| EditableTextReadbackError::TimedOut)?
1005        .map_err(|_| EditableTextReadbackError::Failed)
1006}
1007
1008async fn text_readback_matches(
1009    text: &TextProxy<'_>,
1010    requested: &str,
1011    deadline: Instant,
1012) -> std::result::Result<bool, EditableTextReadbackError> {
1013    let character_count = readback_within(deadline, text.character_count()).await?;
1014    if character_count < 0 {
1015        return Err(EditableTextReadbackError::Failed);
1016    }
1017    if character_count as usize == requested.chars().count() {
1018        return unicode_scalar_text_readback_matches(text, 0, requested, deadline).await;
1019    }
1020
1021    let requested_utf16 = requested.encode_utf16().collect::<Vec<_>>();
1022    if character_count as usize != requested_utf16.len() {
1023        return Ok(false);
1024    }
1025    utf16_text_readback_matches(text, 0, &requested_utf16, deadline).await
1026}
1027
1028/// Whether the text from offset `base` on starts with `requested`, with
1029/// offsets counted in Unicode scalars.
1030async fn unicode_scalar_text_readback_matches(
1031    text: &TextProxy<'_>,
1032    base: usize,
1033    requested: &str,
1034    deadline: Instant,
1035) -> std::result::Result<bool, EditableTextReadbackError> {
1036    let requested_chars = requested.chars().collect::<Vec<_>>();
1037    let mut offset = 0;
1038    while offset < requested_chars.len() {
1039        let end = offset
1040            .saturating_add(EDITABLE_TEXT_READ_CHUNK_UNITS)
1041            .min(requested_chars.len());
1042        let chunk = readback_within(
1043            deadline,
1044            text.get_text((base + offset) as i32, (base + end) as i32),
1045        )
1046        .await?;
1047        if !chunk
1048            .chars()
1049            .eq(requested_chars[offset..end].iter().copied())
1050        {
1051            return Ok(false);
1052        }
1053        offset = end;
1054    }
1055
1056    Ok(true)
1057}
1058
1059/// The same check with offsets counted in UTF-16 code units.
1060async fn utf16_text_readback_matches(
1061    text: &TextProxy<'_>,
1062    base: usize,
1063    requested: &[u16],
1064    deadline: Instant,
1065) -> std::result::Result<bool, EditableTextReadbackError> {
1066    let mut offset = 0;
1067    while offset < requested.len() {
1068        let mut end = offset
1069            .saturating_add(EDITABLE_TEXT_READ_CHUNK_UNITS)
1070            .min(requested.len());
1071        if end < requested.len() && (0xD800..=0xDBFF).contains(&requested[end - 1]) {
1072            end -= 1;
1073        }
1074        let chunk = readback_within(
1075            deadline,
1076            text.get_text((base + offset) as i32, (base + end) as i32),
1077        )
1078        .await?;
1079        if !chunk
1080            .encode_utf16()
1081            .eq(requested[offset..end].iter().copied())
1082        {
1083            return Ok(false);
1084        }
1085        offset = end;
1086    }
1087
1088    Ok(true)
1089}
1090
1091async fn verify_editable_text_contents(
1092    proxy: &AccessibleProxy<'_>,
1093    proxies: &Proxies<'_>,
1094    requested: &str,
1095) -> EditableTextSetOutcome {
1096    let deadline = Instant::now() + EDITABLE_TEXT_VERIFY_TIMEOUT;
1097    match readback_within(deadline, proxy.get_role()).await {
1098        Ok(atspi::Role::PasswordText) => return EditableTextSetOutcome::PasswordUnverifiable,
1099        Ok(_) => {}
1100        Err(EditableTextReadbackError::Failed) => {
1101            return EditableTextSetOutcome::ReadbackFailed;
1102        }
1103        Err(EditableTextReadbackError::TimedOut) => {
1104            return EditableTextSetOutcome::ReadbackTimedOut;
1105        }
1106    }
1107    let text = match readback_within(deadline, proxies.text()).await {
1108        Ok(text) => text,
1109        Err(EditableTextReadbackError::Failed) => {
1110            return EditableTextSetOutcome::ReadbackFailed;
1111        }
1112        Err(EditableTextReadbackError::TimedOut) => {
1113            return EditableTextSetOutcome::ReadbackTimedOut;
1114        }
1115    };
1116
1117    loop {
1118        match text_readback_matches(&text, requested, deadline).await {
1119            Ok(true) => return EditableTextSetOutcome::Verified,
1120            Ok(false) => {}
1121            Err(EditableTextReadbackError::Failed) => {
1122                return EditableTextSetOutcome::ReadbackFailed;
1123            }
1124            Err(EditableTextReadbackError::TimedOut) => {
1125                return EditableTextSetOutcome::ReadbackTimedOut;
1126            }
1127        }
1128
1129        let now = Instant::now();
1130        if now >= deadline {
1131            return EditableTextSetOutcome::MismatchAfterDeadline;
1132        }
1133        sleep_until((now + EDITABLE_TEXT_VERIFY_INTERVAL).min(deadline)).await;
1134        if Instant::now() >= deadline {
1135            return EditableTextSetOutcome::MismatchAfterDeadline;
1136        }
1137    }
1138}
1139
1140/// Characters of a mismatched readback that a failure report quotes.
1141const MAX_REPORTED_READBACK_CHARS: usize = 256;
1142
1143/// Outcome of [`insert_text_at_focus`].
1144#[derive(Debug, Clone, PartialEq, Eq)]
1145pub(crate) enum FocusedTextInsert {
1146    /// The field reads the text at the insertion point and has the expected
1147    /// length.
1148    Verified {
1149        role: String,
1150        replaced_selection: bool,
1151        /// The caret is after the inserted text, where typing leaves it.
1152        caret_after_text: bool,
1153    },
1154    /// No text was changed. The focus is not a field this route can fill; the
1155    /// string says why.
1156    NotEditable(String),
1157    /// No text was changed. The focused element is a password field.
1158    PasswordField,
1159    /// A named password field took the text; it cannot be read back.
1160    PasswordUnverifiable,
1161    /// The app took the edit, but the field does not read back the text at
1162    /// the insertion point.
1163    Mismatch {
1164        expected_count: i32,
1165        read_count: i32,
1166        /// The text read from the insertion point.
1167        read_text: String,
1168        read_truncated: bool,
1169    },
1170    ReadbackFailed,
1171    ReadbackTimedOut,
1172    /// The app refused or failed an edit call.
1173    EditFailed {
1174        reason: String,
1175        may_have_changed: bool,
1176    },
1177}
1178
1179/// Insert `text` at the caret of the focused element in the target window,
1180/// through AT-SPI EditableText, and read it back. The window is the app
1181/// root's window named `window_title` (any title works when the app has one
1182/// window), and it must be active. A selection is replaced, as typing would.
1183/// An empty or fully selected field gets its contents set, the same call
1184/// set_value makes. `Err` means nothing was changed.
1185pub(crate) async fn insert_text_at_focus(
1186    target_pid: u32,
1187    window_title: Option<&str>,
1188    text: &str,
1189) -> Result<FocusedTextInsert> {
1190    let conn = connect().await?;
1191    insert_text_at_focus_on(&conn, target_pid, window_title, text).await
1192}
1193
1194pub(crate) async fn insert_text_at_focus_on(
1195    conn: &AccessibilityConnection,
1196    target_pid: u32,
1197    window_title: Option<&str>,
1198    text: &str,
1199) -> Result<FocusedTextInsert> {
1200    let window = timeout(
1201        ACTION_QUERY_TIMEOUT,
1202        target_window_root(conn, target_pid, window_title),
1203    )
1204    .await
1205    .context("finding the target window in AT-SPI exceeded its 5-second deadline")??;
1206    let window = match window {
1207        Ok(window) => window,
1208        Err(reason) => return Ok(FocusedTextInsert::NotEditable(reason)),
1209    };
1210    let (probe, object_ref) = timeout(
1211        ACTION_QUERY_TIMEOUT,
1212        focused_element_search_from(conn, vec![window], true),
1213    )
1214    .await
1215    .context("the AT-SPI focus search exceeded its 5-second deadline")??;
1216    let (summary, object_ref) = match (probe, object_ref) {
1217        (FocusProbe::Found(summary), Some(object_ref)) => (summary, object_ref),
1218        (FocusProbe::Found(summary), None) => {
1219            return Ok(FocusedTextInsert::NotEditable(format!(
1220                "keyboard focus is on a {} container, not on a text field",
1221                summary.role
1222            )))
1223        }
1224        (FocusProbe::NoneFocused | FocusProbe::ShellOnly, _) => {
1225            return Ok(FocusedTextInsert::NotEditable(
1226                "no element in the target window has keyboard focus".to_string(),
1227            ))
1228        }
1229        (FocusProbe::Incomplete, _) => {
1230            return Ok(FocusedTextInsert::NotEditable(
1231                "the focused element was not found within the AT-SPI search limits".to_string(),
1232            ))
1233        }
1234        (FocusProbe::NoAccessibleApp, _) => {
1235            return Ok(FocusedTextInsert::NotEditable(
1236                "the target app exposes no AT-SPI tree".to_string(),
1237            ))
1238        }
1239    };
1240    let proxy = open_accessible(conn, &object_ref)
1241        .await
1242        .context("failed to open the focused AT-SPI element")?;
1243    let proxies = proxy
1244        .proxies()
1245        .await
1246        .context("failed to read the focused element's interfaces")?;
1247    insert_text_with_proxies(&proxy, &proxies, &summary, text, InsertMode::Focused).await
1248}
1249
1250/// Where an AT-SPI text insert goes: the focused field of the window being
1251/// typed into, or an element the call named, which may not have focus.
1252#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1253enum InsertMode {
1254    Focused,
1255    Named,
1256}
1257
1258impl InsertMode {
1259    fn noun(self) -> &'static str {
1260        match self {
1261            InsertMode::Focused => "focused",
1262            InsertMode::Named => "named",
1263        }
1264    }
1265}
1266
1267/// Insert `text` into the element `object_ref_id` names, without focusing
1268/// it, through AT-SPI EditableText, and read it back. The text goes in at the
1269/// element's caret, or at its end when the caret is not in it; a selection
1270/// is left alone and the caret is not moved. A line feed or tab goes in only
1271/// when the element is multi-line; other control characters are refused. A
1272/// password field gets the text with no readback.
1273pub(crate) async fn insert_text_into_element(
1274    object_ref_id: &str,
1275    text: &str,
1276) -> Result<FocusedTextInsert> {
1277    let conn = connect().await?;
1278    let object_ref = object_ref_from_id(object_ref_id)?;
1279    let proxy = open_accessible(&conn, &object_ref)
1280        .await
1281        .with_context(|| format!("failed to open AT-SPI object {object_ref_id}"))?;
1282    let proxies = proxy
1283        .proxies()
1284        .await
1285        .context("failed to read the element's interfaces")?;
1286    let deadline = Instant::now() + ACTION_QUERY_TIMEOUT;
1287    let role = read_before_edit(deadline, proxy.get_role(), "role").await?;
1288    let state = read_before_edit(deadline, proxy.get_state(), "states").await?;
1289    let summary = FocusedElementSummary {
1290        role: role_name(&proxy).await,
1291        name: optional_string(proxy.name().await.ok()),
1292        editable: supports_editable_text(Some(&proxies)).await,
1293        states: state_labels(state),
1294        is_terminal: role == atspi::Role::Terminal,
1295    };
1296    let multi_line = state.contains(atspi::State::MultiLine);
1297    if let Some(ch) = text
1298        .chars()
1299        .find(|ch| ch.is_control() && !(multi_line && (*ch == '\n' || *ch == '\t')))
1300    {
1301        return Ok(FocusedTextInsert::NotEditable(format!(
1302            "the text has U+{:04X}, which the named {} would not take as text; send the key with press_key",
1303            ch as u32, summary.role
1304        )));
1305    }
1306    if role == atspi::Role::PasswordText {
1307        return insert_password_text(&proxy, &proxies, &summary, text, deadline).await;
1308    }
1309    insert_text_with_proxies(&proxy, &proxies, &summary, text, InsertMode::Named).await
1310}
1311
1312/// A password field's text cannot be read back, so the insert is sent at the
1313/// caret (or the end) and reported as unverifiable, as set_value does.
1314async fn insert_password_text(
1315    proxy: &AccessibleProxy<'_>,
1316    proxies: &Proxies<'_>,
1317    summary: &FocusedElementSummary,
1318    requested: &str,
1319    deadline: Instant,
1320) -> Result<FocusedTextInsert> {
1321    if !summary.states.iter().any(|state| state == "editable") {
1322        return Ok(FocusedTextInsert::NotEditable(format!(
1323            "the named {} is not editable",
1324            summary.role
1325        )));
1326    }
1327    let Ok(editable) = proxies.editable_text().await else {
1328        return Ok(FocusedTextInsert::NotEditable(format!(
1329            "the named {} does not expose AT-SPI EditableText",
1330            summary.role
1331        )));
1332    };
1333    // Without Text the insertion point is unknown, and SetTextContents would
1334    // replace whatever the field holds.
1335    let Ok(text) = proxies.text().await else {
1336        return Ok(FocusedTextInsert::NotEditable(format!(
1337            "the named {} does not expose AT-SPI Text, so its insertion point is unknown",
1338            summary.role
1339        )));
1340    };
1341    let count = read_before_edit(deadline, text.character_count(), "character count").await?;
1342    let caret = read_before_edit(deadline, text.caret_offset(), "caret offset").await?;
1343    let call = if count <= 0 {
1344        edit_call(editable.set_text_contents(requested), "SetTextContents").await
1345    } else {
1346        let point = if (0..=count).contains(&caret) {
1347            caret
1348        } else {
1349            count
1350        };
1351        let length = match insert_text_length(proxy, requested, deadline).await {
1352            Ok(length) => length,
1353            Err(reason) => return Ok(FocusedTextInsert::NotEditable(reason)),
1354        };
1355        edit_call(editable.insert_text(point, requested, length), "InsertText").await
1356    };
1357    Ok(match call {
1358        Ok(()) => FocusedTextInsert::PasswordUnverifiable,
1359        Err(EditCallError::Refused) => FocusedTextInsert::EditFailed {
1360            reason: "the app refused the password field edit".to_string(),
1361            may_have_changed: false,
1362        },
1363        Err(EditCallError::Failed(reason)) => FocusedTextInsert::EditFailed {
1364            reason,
1365            may_have_changed: true,
1366        },
1367    })
1368}
1369
1370/// Role, state names and action names of the element `object_ref_id` names,
1371/// read live, for mapping a key to its action.
1372pub(crate) async fn element_role_states_actions(
1373    object_ref_id: &str,
1374) -> Result<(String, Vec<String>, Vec<String>)> {
1375    timeout(ACTION_QUERY_TIMEOUT, async {
1376        let conn = connect().await?;
1377        let object_ref = object_ref_from_id(object_ref_id)?;
1378        let proxy = open_accessible(&conn, &object_ref)
1379            .await
1380            .with_context(|| format!("failed to open AT-SPI object {object_ref_id}"))?;
1381        let states = state_labels(proxy.get_state().await.context("failed to read states")?);
1382        let actions = match proxy.proxies().await?.action().await {
1383            Ok(action) => read_actions(&action)
1384                .await?
1385                .into_iter()
1386                .map(|action| action.name)
1387                .collect(),
1388            Err(_) => Vec::new(),
1389        };
1390        Ok::<_, anyhow::Error>((role_name(&proxy).await, states, actions))
1391    })
1392    .await
1393    .context("reading the element exceeded its 5-second deadline")?
1394}
1395
1396/// Gives `object_ref_id` the keyboard focus of its window through AT-SPI
1397/// Component.GrabFocus, so focused input to that window reaches it.
1398pub(crate) async fn focus_element(object_ref_id: &str) -> Result<()> {
1399    timeout(ACTION_QUERY_TIMEOUT, async {
1400        let conn = connect().await?;
1401        let object_ref = object_ref_from_id(object_ref_id)?;
1402        let proxy = open_accessible(&conn, &object_ref)
1403            .await
1404            .with_context(|| format!("failed to open AT-SPI object {object_ref_id}"))?;
1405        let component = proxy
1406            .proxies()
1407            .await?
1408            .component()
1409            .await
1410            .context("the element has no AT-SPI Component, so it cannot take keyboard focus")?;
1411        if !component
1412            .grab_focus()
1413            .await
1414            .context("AT-SPI GrabFocus failed")?
1415        {
1416            return Err(anyhow!(
1417                "the element did not take keyboard focus (AT-SPI GrabFocus returned false)"
1418            ));
1419        }
1420        Ok::<_, anyhow::Error>(())
1421    })
1422    .await
1423    .context("focusing the element exceeded its 5-second deadline")?
1424}
1425
1426/// The AT-SPI window of the app owning `target_pid` that matches the verified
1427/// compositor window, or why none can be proven to. One app root can hold
1428/// several windows (Chromium holds them all), and its AT-SPI focus can lag
1429/// behind the compositor's, so a focused field elsewhere in the app is not
1430/// the target. The window must be active.
1431async fn target_window_root(
1432    conn: &AccessibilityConnection,
1433    target_pid: u32,
1434    window_title: Option<&str>,
1435) -> Result<std::result::Result<ObjectRefOwned, String>> {
1436    let mut remaining_registry_reads = MAX_DISCOVERY_ROOTS;
1437    let roots = registry_children(conn, MAX_DISCOVERY_ROOTS, &mut remaining_registry_reads).await?;
1438    let mut remaining_filter_reads = MAX_DISCOVERY_CHILD_READS;
1439    let selected = select_roots(
1440        conn,
1441        roots,
1442        None,
1443        Some(target_pid),
1444        None,
1445        &mut remaining_filter_reads,
1446    )
1447    .await;
1448    if selected.pid != Some(target_pid) {
1449        return Ok(Err("the target app exposes no AT-SPI tree".to_string()));
1450    }
1451    let mut windows = Vec::new();
1452    let mut labels = Vec::new();
1453    let mut remaining_child_reads = MAX_DISCOVERY_CHILD_READS;
1454    for root in &selected.roots {
1455        let Ok(root) = open_accessible(conn, root).await else {
1456            continue;
1457        };
1458        let Ok(batch) =
1459            children_up_to(&root, MAX_DISCOVERY_ROOTS, &mut remaining_child_reads).await
1460        else {
1461            continue;
1462        };
1463        for child in batch.items {
1464            let Ok(proxy) = open_accessible(conn, &child).await else {
1465                continue;
1466            };
1467            let role = role_name(&proxy).await;
1468            if !is_window_role(&role) {
1469                continue;
1470            }
1471            let name = optional_string(proxy.name().await.ok());
1472            let active = proxy
1473                .get_state()
1474                .await
1475                .is_ok_and(|state| state.contains(atspi::State::Active));
1476            labels.push((role, name));
1477            windows.push((child, active));
1478        }
1479    }
1480    let chosen = match windows.len() {
1481        0 => return Ok(Err("the target app exposes no AT-SPI window".to_string())),
1482        1 => 0,
1483        count => {
1484            let Some(chosen) = window_title.and_then(|title| matching_window(&labels, title))
1485            else {
1486                return Ok(Err(format!(
1487                    "the target window could not be matched to one of the app's {count} AT-SPI windows"
1488                )));
1489            };
1490            chosen
1491        }
1492    };
1493    let (window, active) = windows.swap_remove(chosen);
1494    if !active {
1495        return Ok(Err(format!(
1496            "the target window's AT-SPI {} is not active, so its focus may be stale",
1497            labels[chosen].0
1498        )));
1499    }
1500    Ok(Ok(window))
1501}
1502
1503async fn read_before_edit<T, E: std::fmt::Display>(
1504    deadline: Instant,
1505    read: impl Future<Output = std::result::Result<T, E>>,
1506    what: &str,
1507) -> Result<T> {
1508    match timeout_at(deadline, read).await {
1509        Ok(Ok(value)) => Ok(value),
1510        Ok(Err(error)) => Err(anyhow!("failed to read the field's {what}: {error}")),
1511        Err(_) => Err(anyhow!("reading the field's {what} timed out")),
1512    }
1513}
1514
1515/// InsertText's length argument for `requested`. GTK and the other ATK
1516/// bridges count it in bytes, as the AT-SPI documentation does. Qt's bridge
1517/// resizes the text to that many UTF-16 code units, padding a longer text.
1518/// ASCII text has one length in every unit; other text needs the app's
1519/// toolkit, and the error explains a toolkit that cannot be read.
1520async fn insert_text_length(
1521    proxy: &AccessibleProxy<'_>,
1522    requested: &str,
1523    deadline: Instant,
1524) -> std::result::Result<i32, String> {
1525    let too_long = |_| "the text is too long for AT-SPI InsertText".to_string();
1526    if requested.is_ascii() {
1527        return i32::try_from(requested.len()).map_err(too_long);
1528    }
1529    let Some(toolkit) = toolkit_name(proxy, deadline).await else {
1530        return Err("the app's toolkit could not be read, and InsertText counts the length of non-ASCII text differently per toolkit".to_string());
1531    };
1532    if toolkit.trim().to_ascii_lowercase().starts_with("qt") {
1533        i32::try_from(requested.encode_utf16().count()).map_err(too_long)
1534    } else {
1535        i32::try_from(requested.len()).map_err(too_long)
1536    }
1537}
1538
1539/// `ToolkitName` of the element's application: its `GetApplication` root, or
1540/// else the root on the element's own connection.
1541async fn toolkit_name(proxy: &AccessibleProxy<'_>, deadline: Instant) -> Option<String> {
1542    let connection = proxy.inner().connection();
1543    let application = timeout_at(deadline, proxy.get_application())
1544        .await
1545        .ok()
1546        .and_then(|reply| reply.ok())
1547        .filter(|application| !application.is_null());
1548    let (name, path) = match &application {
1549        Some(application) => (
1550            application.name_as_str()?.to_string(),
1551            application.path_as_str().to_string(),
1552        ),
1553        None => (
1554            proxy.inner().destination().to_string(),
1555            "/org/a11y/atspi/accessible/root".to_string(),
1556        ),
1557    };
1558    let app = atspi::proxy::application::ApplicationProxy::builder(connection)
1559        .destination(name)
1560        .ok()?
1561        .path(path)
1562        .ok()?
1563        .cache_properties(zbus::proxy::CacheProperties::No)
1564        .build()
1565        .await
1566        .ok()?;
1567    timeout_at(deadline, app.toolkit_name()).await.ok()?.ok()
1568}
1569
1570async fn insert_text_with_proxies(
1571    proxy: &AccessibleProxy<'_>,
1572    proxies: &Proxies<'_>,
1573    summary: &FocusedElementSummary,
1574    requested: &str,
1575    mode: InsertMode,
1576) -> Result<FocusedTextInsert> {
1577    let deadline = Instant::now() + ACTION_QUERY_TIMEOUT;
1578    let what = mode.noun();
1579    let role = read_before_edit(deadline, proxy.get_role(), "role").await?;
1580    if role == atspi::Role::PasswordText || summary.role.to_ascii_lowercase().contains("password") {
1581        return Ok(FocusedTextInsert::PasswordField);
1582    }
1583    if summary.is_terminal || role == atspi::Role::Terminal {
1584        return Ok(FocusedTextInsert::NotEditable(format!(
1585            "the {what} element is a terminal"
1586        )));
1587    }
1588    if matches!(role, atspi::Role::Invalid | atspi::Role::Unknown) {
1589        return Ok(FocusedTextInsert::NotEditable(format!(
1590            "the {what} element's role does not show whether it hides input"
1591        )));
1592    }
1593    if !summary.states.iter().any(|state| state == "editable") {
1594        return Ok(FocusedTextInsert::NotEditable(format!(
1595            "the {what} {} is not editable",
1596            summary.role
1597        )));
1598    }
1599    let Ok(editable) = proxies.editable_text().await else {
1600        return Ok(FocusedTextInsert::NotEditable(format!(
1601            "the {what} {} does not expose AT-SPI EditableText",
1602            summary.role
1603        )));
1604    };
1605    let Ok(text) = proxies.text().await else {
1606        return Ok(FocusedTextInsert::NotEditable(format!(
1607            "the {what} {} does not expose AT-SPI Text, so the result could not be read back",
1608            summary.role
1609        )));
1610    };
1611    let count = read_before_edit(deadline, text.character_count(), "character count").await?;
1612    let caret = read_before_edit(deadline, text.caret_offset(), "caret offset").await?;
1613    let selections =
1614        read_before_edit(deadline, text_selection_count(&text), "selection count").await?;
1615    let (start, end) = match selections {
1616        // A named element is not being typed into: its caret marks the
1617        // insertion point (the end when it has none) and a selection it
1618        // kept from earlier is left alone.
1619        _ if mode == InsertMode::Named => {
1620            let point = if (0..=count).contains(&caret) {
1621                caret
1622            } else {
1623                count
1624            };
1625            (point, point)
1626        }
1627        ..=0 => (caret, caret),
1628        1 => {
1629            let (a, b) = read_before_edit(deadline, text.get_selection(0), "selection").await?;
1630            (a.min(b), a.max(b))
1631        }
1632        n => {
1633            return Ok(FocusedTextInsert::NotEditable(format!(
1634                "the field has {n} selections, so the insertion point is ambiguous"
1635            )))
1636        }
1637    };
1638    if count < 0 || start < 0 || end > count {
1639        return Err(anyhow!(
1640            "the field reported an insertion point ({start}..{end}) outside its {count} characters"
1641        ));
1642    }
1643
1644    let replaced_selection = start < end;
1645    let whole_field = start == 0 && end == count;
1646    // Rewriting the whole field for a partial edit would flatten embedded
1647    // objects and formatting, so a partial edit always uses InsertText.
1648    let insert_length = if whole_field {
1649        None
1650    } else {
1651        match insert_text_length(proxy, requested, deadline).await {
1652            Ok(length) => Some(length),
1653            Err(reason) => return Ok(FocusedTextInsert::NotEditable(reason)),
1654        }
1655    };
1656    let untouched = read_untouched_text(&text, start, end, count, deadline).await?;
1657
1658    if let Some(length) = insert_length {
1659        if replaced_selection {
1660            match edit_call(editable.delete_text(start, end), "DeleteText").await {
1661                Ok(()) => {}
1662                Err(EditCallError::Refused) => {
1663                    return Ok(FocusedTextInsert::EditFailed {
1664                        reason: "the app refused to delete the selection".to_string(),
1665                        may_have_changed: false,
1666                    })
1667                }
1668                Err(EditCallError::Failed(reason)) => {
1669                    return Ok(FocusedTextInsert::EditFailed {
1670                        reason,
1671                        may_have_changed: true,
1672                    })
1673                }
1674            }
1675        }
1676        match edit_call(editable.insert_text(start, requested, length), "InsertText").await {
1677            Ok(()) => {}
1678            Err(EditCallError::Refused) => {
1679                return Ok(FocusedTextInsert::EditFailed {
1680                    reason: if replaced_selection {
1681                        "the app deleted the selection but refused InsertText".to_string()
1682                    } else {
1683                        "the app refused InsertText".to_string()
1684                    },
1685                    may_have_changed: replaced_selection,
1686                })
1687            }
1688            Err(EditCallError::Failed(reason)) => {
1689                return Ok(FocusedTextInsert::EditFailed {
1690                    reason,
1691                    may_have_changed: true,
1692                })
1693            }
1694        }
1695    } else {
1696        match edit_call(editable.set_text_contents(requested), "SetTextContents").await {
1697            Ok(()) => {}
1698            Err(EditCallError::Refused) => {
1699                return Ok(FocusedTextInsert::EditFailed {
1700                    reason: "the app refused SetTextContents".to_string(),
1701                    may_have_changed: false,
1702                })
1703            }
1704            Err(EditCallError::Failed(reason)) => {
1705                return Ok(FocusedTextInsert::EditFailed {
1706                    reason,
1707                    may_have_changed: true,
1708                })
1709            }
1710        }
1711    }
1712
1713    verify_inserted_text(
1714        &text,
1715        start,
1716        count - (end - start),
1717        requested,
1718        &untouched,
1719        mode == InsertMode::Focused,
1720    )
1721    .await
1722    .map(|outcome| match outcome {
1723        InsertReadback::Verified { caret_after_text } => FocusedTextInsert::Verified {
1724            role: summary.role.clone(),
1725            replaced_selection,
1726            caret_after_text,
1727        },
1728        InsertReadback::Other(outcome) => outcome,
1729    })
1730}
1731
1732enum EditCallError {
1733    /// The app answered false: it did not make the edit.
1734    Refused,
1735    /// The call failed or timed out, so the edit may have happened.
1736    Failed(String),
1737}
1738
1739/// One EditableText call, bounded like the other AT-SPI calls.
1740async fn edit_call(
1741    call: impl Future<Output = zbus::Result<bool>>,
1742    name: &str,
1743) -> std::result::Result<(), EditCallError> {
1744    match timeout(ACTION_QUERY_TIMEOUT, call).await {
1745        Ok(Ok(true)) => Ok(()),
1746        Ok(Ok(false)) => Err(EditCallError::Refused),
1747        Ok(Err(error)) => Err(EditCallError::Failed(format!("{name} failed: {error}"))),
1748        Err(_) => Err(EditCallError::Failed(format!(
1749            "{name} did not answer within 5 seconds"
1750        ))),
1751    }
1752}
1753
1754/// Characters on each side of the edit that a large field's readback checks.
1755const UNTOUCHED_SPAN_UNITS: i32 = 32;
1756
1757/// The text an edit of `start..end` must leave alone, read before the edit.
1758enum UntouchedText {
1759    /// A field of at most `MAX_TEXT_READBACK_CHARS`: everything before and
1760    /// after the edit.
1761    Whole { before: String, after: String },
1762    /// A larger field: the spans just before and after the edit.
1763    Spans {
1764        before: String,
1765        before_units: i32,
1766        after: String,
1767        after_units: i32,
1768    },
1769}
1770
1771async fn read_untouched_text(
1772    text: &TextProxy<'_>,
1773    start: i32,
1774    end: i32,
1775    count: i32,
1776    deadline: Instant,
1777) -> Result<UntouchedText> {
1778    if count <= MAX_TEXT_READBACK_CHARS {
1779        return Ok(UntouchedText::Whole {
1780            before: read_before_edit(deadline, text.get_text(0, start), "text").await?,
1781            after: read_before_edit(deadline, text.get_text(end, count), "text").await?,
1782        });
1783    }
1784    let before_units = start.min(UNTOUCHED_SPAN_UNITS);
1785    let after_units = (count - end).min(UNTOUCHED_SPAN_UNITS);
1786    Ok(UntouchedText::Spans {
1787        before: read_before_edit(deadline, text.get_text(start - before_units, start), "text")
1788            .await?,
1789        before_units,
1790        after: read_before_edit(deadline, text.get_text(end, end + after_units), "text").await?,
1791        after_units,
1792    })
1793}
1794
1795enum InsertReadback {
1796    Verified { caret_after_text: bool },
1797    Other(FocusedTextInsert),
1798}
1799
1800/// Whether the field holds `requested` at `start`, `units` long in the app's
1801/// offsets, with the untouched text unchanged around it.
1802async fn edit_reads_back(
1803    text: &TextProxy<'_>,
1804    start: i32,
1805    units: i32,
1806    read_count: i32,
1807    requested: &str,
1808    untouched: &UntouchedText,
1809    deadline: Instant,
1810) -> std::result::Result<bool, EditableTextReadbackError> {
1811    match untouched {
1812        UntouchedText::Whole { before, after } => {
1813            let contents = readback_within(deadline, text.get_text(0, read_count)).await?;
1814            Ok(
1815                contents.len() == before.len() + requested.len() + after.len()
1816                    && contents.starts_with(before.as_str())
1817                    && contents[before.len()..].starts_with(requested)
1818                    && contents.ends_with(after.as_str()),
1819            )
1820        }
1821        UntouchedText::Spans {
1822            before,
1823            before_units,
1824            after,
1825            after_units,
1826        } => {
1827            let inserted = readback_within(deadline, text.get_text(start, start + units)).await?;
1828            if inserted != requested {
1829                return Ok(false);
1830            }
1831            let read_before =
1832                readback_within(deadline, text.get_text(start - before_units, start)).await?;
1833            let after_start = start + units;
1834            let read_after = readback_within(
1835                deadline,
1836                text.get_text(after_start, after_start + after_units),
1837            )
1838            .await?;
1839            Ok(&read_before == before && &read_after == after)
1840        }
1841    }
1842}
1843
1844/// Poll until the edit reads back: `requested` at `start`, `kept` other
1845/// characters in Unicode scalars or UTF-16 code units (whichever the app
1846/// counts in), and the untouched text unchanged. Then put the caret after the
1847/// text.
1848async fn verify_inserted_text(
1849    text: &TextProxy<'_>,
1850    start: i32,
1851    kept: i32,
1852    requested: &str,
1853    untouched: &UntouchedText,
1854    move_caret: bool,
1855) -> Result<InsertReadback> {
1856    let deadline = Instant::now() + EDITABLE_TEXT_VERIFY_TIMEOUT;
1857    let scalars = requested.chars().count() as i64;
1858    let utf16 = requested.encode_utf16().count() as i64;
1859    let mut read_count = 0;
1860    // A read cut by the deadline after the field already read back wrong is
1861    // a mismatch, not a readback timeout.
1862    let mut mismatched = false;
1863    loop {
1864        let count = match readback_within(deadline, text.character_count()).await {
1865            Ok(count) => count,
1866            Err(EditableTextReadbackError::Failed) => {
1867                return Ok(InsertReadback::Other(FocusedTextInsert::ReadbackFailed))
1868            }
1869            Err(EditableTextReadbackError::TimedOut) => {
1870                if mismatched {
1871                    break;
1872                }
1873                return Ok(InsertReadback::Other(FocusedTextInsert::ReadbackTimedOut));
1874            }
1875        };
1876        read_count = count;
1877        let units = i64::from(read_count) - i64::from(kept);
1878        let matched = if units == scalars || units == utf16 {
1879            edit_reads_back(
1880                text,
1881                start,
1882                units as i32,
1883                read_count,
1884                requested,
1885                untouched,
1886                deadline,
1887            )
1888            .await
1889            .map(|matched| matched.then_some(units))
1890        } else {
1891            Ok(None)
1892        };
1893        match matched {
1894            Ok(Some(units)) => {
1895                let after = (i64::from(start) + units) as i32;
1896                let caret_deadline = Instant::now() + EDITABLE_TEXT_VERIFY_TIMEOUT;
1897                let caret_after_text =
1898                    match readback_within(caret_deadline, text.caret_offset()).await {
1899                        Ok(caret) if caret == after => true,
1900                        // Moving the caret of an element that is not
1901                        // being typed into can focus it inside its app.
1902                        _ if !move_caret => false,
1903                        _ => matches!(
1904                            readback_within(caret_deadline, text.set_caret_offset(after)).await,
1905                            Ok(true)
1906                        ),
1907                    };
1908                return Ok(InsertReadback::Verified { caret_after_text });
1909            }
1910            Ok(None) => mismatched = true,
1911            Err(EditableTextReadbackError::Failed) => {
1912                return Ok(InsertReadback::Other(FocusedTextInsert::ReadbackFailed))
1913            }
1914            Err(EditableTextReadbackError::TimedOut) => {
1915                if mismatched {
1916                    break;
1917                }
1918                return Ok(InsertReadback::Other(FocusedTextInsert::ReadbackTimedOut));
1919            }
1920        }
1921        let now = Instant::now();
1922        if now >= deadline {
1923            break;
1924        }
1925        sleep_until((now + EDITABLE_TEXT_VERIFY_INTERVAL).min(deadline)).await;
1926        if Instant::now() >= deadline {
1927            break;
1928        }
1929    }
1930
1931    // Quote what the field holds where the text should be.
1932    let wanted = scalars.max(utf16);
1933    let shown = wanted.min(MAX_REPORTED_READBACK_CHARS as i64);
1934    let read_end = (i64::from(start) + shown).min(i64::from(read_count.max(0)));
1935    let read_text = if read_end > i64::from(start) {
1936        let quote_deadline = Instant::now() + EDITABLE_TEXT_VERIFY_TIMEOUT;
1937        readback_within(quote_deadline, text.get_text(start, read_end as i32))
1938            .await
1939            .unwrap_or_default()
1940    } else {
1941        String::new()
1942    };
1943    let read_truncated = wanted > shown;
1944    Ok(InsertReadback::Other(FocusedTextInsert::Mismatch {
1945        expected_count: (i64::from(kept) + scalars) as i32,
1946        read_count,
1947        read_text,
1948        read_truncated,
1949    }))
1950}
1951
1952async fn connect() -> Result<AccessibilityConnection> {
1953    hydrate_session_bus_env();
1954    AccessibilityConnection::new()
1955        .await
1956        .context("failed to connect to AT-SPI bus")
1957}
1958
1959/// Open an `AccessibleProxy` for an object on the a11y bus.
1960///
1961/// We deliberately avoid `AccessibilityConnection::object_as_accessible` (the
1962/// `P2P` trait). For apps that advertise a peer-to-peer bus address it routes
1963/// reads over that socket, but for apps that don't (notably GTK4 apps such as
1964/// Nautilus / Text Editor / baobab, which don't implement the legacy
1965/// `GetApplicationBusAddress`) it falls back to a proxy built with only a path
1966/// and *no destination*. On the shared a11y bus that proxy can't address the
1967/// app and every call fails with `ServiceUnknown`, which surfaces as an empty
1968/// tree (`role: "unknown"`, `child_count: 0`). `as_accessible_proxy` always
1969/// pins the destination to the object's bus name, so it works for every app
1970/// regardless of P2P support. See issue #31.
1971async fn open_accessible<'r>(
1972    conn: &AccessibilityConnection,
1973    object_ref: &'r ObjectRefOwned,
1974) -> Result<AccessibleProxy<'r>, atspi::AtspiError> {
1975    object_ref.as_accessible_proxy(conn.connection()).await
1976}
1977
1978async fn registry_children(
1979    conn: &AccessibilityConnection,
1980    limit: usize,
1981    remaining_child_reads: &mut usize,
1982) -> Result<Vec<ObjectRefOwned>> {
1983    let root = conn
1984        .root_accessible_on_registry()
1985        .await
1986        .context("failed to open AT-SPI registry root")?;
1987    let batch = children_up_to(&root, limit, remaining_child_reads)
1988        .await
1989        .context("failed to read AT-SPI registry children")?;
1990    if batch.all_failed() {
1991        return Err(anyhow!(
1992            "AT-SPI registry reported children, but every indexed child read failed"
1993        ));
1994    }
1995    Ok(batch.items)
1996}
1997
1998struct SelectedRoots {
1999    roots: Vec<ObjectRefOwned>,
2000    scoped: bool,
2001    /// Set only when the roots were chosen because they belong to this pid.
2002    pid: Option<u32>,
2003    app_filter_matched: bool,
2004}
2005
2006/// Normalized app-name filter, or `None` when the caller passed nothing usable.
2007/// A `None` needle without a PID target means the snapshot covers the whole desktop.
2008fn app_name_needle(app_name_or_bundle_identifier: Option<&str>) -> Option<String> {
2009    app_name_or_bundle_identifier
2010        .map(str::trim)
2011        .filter(|value| !value.is_empty())
2012        .map(|value| value.to_ascii_lowercase())
2013}
2014
2015async fn select_roots(
2016    conn: &AccessibilityConnection,
2017    roots: Vec<ObjectRefOwned>,
2018    app_name_or_bundle_identifier: Option<&str>,
2019    target_pid: Option<u32>,
2020    pid_fallback_name: Option<&str>,
2021    remaining_child_reads: &mut usize,
2022) -> SelectedRoots {
2023    let needle = app_name_needle(app_name_or_bundle_identifier);
2024    let dbus = DBusProxy::new(conn.connection()).await.ok();
2025    let mut remaining = roots;
2026
2027    if let Some(target_pid) = target_pid {
2028        let mut pid_and_filter_matches = Vec::new();
2029        let mut pid_matches = Vec::new();
2030        let mut non_pid_matches = Vec::new();
2031
2032        for object_ref in remaining {
2033            if object_ref_pid(dbus.as_ref(), &object_ref).await == Some(target_pid) {
2034                if let Some(needle) = needle.as_deref() {
2035                    if root_matches(conn, &object_ref, needle, remaining_child_reads).await {
2036                        pid_and_filter_matches.push(object_ref);
2037                    } else {
2038                        pid_matches.push(object_ref);
2039                    }
2040                } else {
2041                    pid_matches.push(object_ref);
2042                }
2043            } else {
2044                non_pid_matches.push(object_ref);
2045            }
2046        }
2047
2048        if !pid_and_filter_matches.is_empty() {
2049            return SelectedRoots {
2050                roots: pid_and_filter_matches,
2051                scoped: true,
2052                pid: Some(target_pid),
2053                app_filter_matched: true,
2054            };
2055        }
2056        if !pid_matches.is_empty() {
2057            return SelectedRoots {
2058                roots: pid_matches,
2059                scoped: true,
2060                pid: Some(target_pid),
2061                app_filter_matched: needle.is_none(),
2062            };
2063        }
2064
2065        if needle.is_none() {
2066            // A listed window's pid can own no root: a Flatpak app registers
2067            // through xdg-dbus-proxy. Its name then finds the root, and the
2068            // tree records no pid, so element calls check each node's owner.
2069            if let Some(fallback) = app_name_needle(pid_fallback_name) {
2070                let mut selected = Vec::new();
2071                for object_ref in non_pid_matches {
2072                    if root_matches(conn, &object_ref, &fallback, remaining_child_reads).await {
2073                        selected.push(object_ref);
2074                    }
2075                }
2076                if !selected.is_empty() {
2077                    return SelectedRoots {
2078                        roots: selected,
2079                        scoped: true,
2080                        pid: None,
2081                        app_filter_matched: true,
2082                    };
2083                }
2084            }
2085            // A PID-only target that disappeared must not widen to the desktop.
2086            return SelectedRoots {
2087                roots: Vec::new(),
2088                scoped: true,
2089                pid: None,
2090                app_filter_matched: false,
2091            };
2092        }
2093
2094        remaining = non_pid_matches;
2095    }
2096
2097    let Some(needle) = needle.as_deref() else {
2098        return SelectedRoots {
2099            roots: remaining,
2100            scoped: false,
2101            pid: None,
2102            app_filter_matched: true,
2103        };
2104    };
2105
2106    let mut selected = Vec::new();
2107    for object_ref in remaining {
2108        if root_matches(conn, &object_ref, needle, remaining_child_reads).await {
2109            selected.push(object_ref);
2110        }
2111    }
2112
2113    let app_filter_matched = !selected.is_empty();
2114    SelectedRoots {
2115        roots: selected,
2116        scoped: true,
2117        pid: None,
2118        app_filter_matched,
2119    }
2120}
2121
2122async fn root_matches(
2123    conn: &AccessibilityConnection,
2124    object_ref: &ObjectRefOwned,
2125    needle: &str,
2126    remaining_child_reads: &mut usize,
2127) -> bool {
2128    let Ok(proxy) = open_accessible(conn, object_ref).await else {
2129        return object_ref_id(object_ref)
2130            .to_ascii_lowercase()
2131            .contains(needle);
2132    };
2133
2134    if proxy_matches(&proxy, object_ref, needle).await {
2135        return true;
2136    }
2137
2138    for child_ref in children_up_to(&proxy, ROOT_MATCH_CHILD_LIMIT, remaining_child_reads)
2139        .await
2140        .map(|batch| batch.items)
2141        .unwrap_or_default()
2142    {
2143        let Ok(child_proxy) = open_accessible(conn, &child_ref).await else {
2144            continue;
2145        };
2146        if proxy_matches(&child_proxy, &child_ref, needle).await {
2147            return true;
2148        }
2149    }
2150
2151    false
2152}
2153
2154async fn proxy_matches(
2155    proxy: &AccessibleProxy<'_>,
2156    object_ref: &ObjectRefOwned,
2157    needle: &str,
2158) -> bool {
2159    let name = proxy.name().await.unwrap_or_default();
2160    let role = proxy.get_role_name().await.unwrap_or_default();
2161    format!("{} {} {}", object_ref_id(object_ref), name, role)
2162        .to_ascii_lowercase()
2163        .contains(needle)
2164}
2165
2166async fn read_app_summary(
2167    proxy: &AccessibleProxy<'_>,
2168    object_ref: &ObjectRefOwned,
2169    dbus: Option<&DBusProxy<'_>>,
2170) -> AccessibleAppSummary {
2171    AccessibleAppSummary {
2172        object_ref: object_ref_id(object_ref),
2173        name: optional_string(proxy.name().await.ok()),
2174        pid: object_ref_pid(dbus, object_ref).await,
2175        role: role_name(proxy).await,
2176        child_count: proxy.child_count().await.unwrap_or_default(),
2177        bounds: bounds(proxy).await,
2178    }
2179}
2180
2181async fn read_node(
2182    proxy: &AccessibleProxy<'_>,
2183    object_ref: &ObjectRefOwned,
2184    index: u32,
2185    parent_index: Option<u32>,
2186    depth: u32,
2187) -> AccessibilityNode {
2188    let proxies = proxy.proxies().await.ok();
2189
2190    AccessibilityNode {
2191        index,
2192        parent_index,
2193        depth,
2194        object_ref: object_ref_id(object_ref),
2195        role: role_name(proxy).await,
2196        name: optional_string(proxy.name().await.ok()),
2197        description: optional_string(proxy.description().await.ok()),
2198        child_count: proxy.child_count().await.unwrap_or_default(),
2199        bounds: bounds_from_proxies(proxies.as_ref(), proxy).await,
2200        states: states_from_proxy(proxy).await,
2201        actions: actions_from_proxies(proxies.as_ref()).await,
2202        value: value_from_proxies(proxies.as_ref()).await,
2203        text: text_from_proxies(proxies.as_ref()).await,
2204        supports_editable_text: supports_editable_text(proxies.as_ref()).await,
2205    }
2206}
2207
2208/// Role reported when neither AT-SPI role read succeeds.
2209pub(crate) const UNKNOWN_ROLE: &str = "unknown";
2210
2211async fn role_name(proxy: &AccessibleProxy<'_>) -> String {
2212    if let Ok(role) = proxy.get_role_name().await {
2213        if !role.trim().is_empty() {
2214            return role;
2215        }
2216    }
2217    proxy
2218        .get_role()
2219        .await
2220        .map(|role| format!("{role:?}"))
2221        .unwrap_or_else(|_| UNKNOWN_ROLE.to_string())
2222}
2223
2224async fn bounds(proxy: &AccessibleProxy<'_>) -> Option<Bounds> {
2225    bounds_from_proxies(proxy.proxies().await.ok().as_ref(), proxy).await
2226}
2227
2228/// Pid of the process that owns an AT-SPI object ref (`:bus/path`), from the
2229/// accessibility bus. `None` when the owner is gone or the bus cannot say.
2230pub(crate) async fn object_ref_owner_pid(object_ref_id: &str) -> Result<Option<u32>> {
2231    let object_ref = object_ref_from_id(object_ref_id)?;
2232    let conn = connect().await?;
2233    let dbus = DBusProxy::new(conn.connection()).await.ok();
2234    Ok(object_ref_pid(dbus.as_ref(), &object_ref).await)
2235}
2236
2237/// PID of the application root, which may differ from an embedded element's process.
2238pub(crate) async fn object_ref_application_pid(object_ref_id: &str) -> Result<Option<u32>> {
2239    let object_ref = object_ref_from_id(object_ref_id)?;
2240    let conn = connect().await?;
2241    let application = timeout(ACTION_QUERY_TIMEOUT, async {
2242        let proxy = open_accessible(&conn, &object_ref).await.ok()?;
2243        proxy.get_application().await.ok()
2244    })
2245    .await
2246    .ok()
2247    .flatten()
2248    .filter(|application| !application.is_null());
2249    let dbus = DBusProxy::new(conn.connection()).await.ok();
2250    Ok(object_ref_pid(dbus.as_ref(), application.as_ref().unwrap_or(&object_ref)).await)
2251}
2252
2253async fn object_ref_pid(dbus: Option<&DBusProxy<'_>>, object_ref: &ObjectRefOwned) -> Option<u32> {
2254    let dbus = dbus?;
2255    let bus_name = BusName::try_from(object_ref.name_as_str()?.to_string()).ok()?;
2256    dbus.get_connection_unix_process_id(bus_name).await.ok()
2257}
2258
2259async fn bounds_from_proxies(
2260    proxies: Option<&atspi::proxy::proxy_ext::Proxies<'_>>,
2261    proxy: &AccessibleProxy<'_>,
2262) -> Option<Bounds> {
2263    let owned_proxies;
2264    let proxies = if let Some(proxies) = proxies {
2265        proxies
2266    } else {
2267        owned_proxies = proxy.proxies().await.ok()?;
2268        &owned_proxies
2269    };
2270    let component = proxies.component().await.ok()?;
2271    let (x, y, width, height) = component.get_extents(CoordType::Screen).await.ok()?;
2272    normalize_bounds(Bounds {
2273        x,
2274        y,
2275        width,
2276        height,
2277    })
2278}
2279
2280fn normalize_bounds(bounds: Bounds) -> Option<Bounds> {
2281    if bounds.width <= 0 || bounds.height <= 0 {
2282        return None;
2283    }
2284    if bounds.x <= i32::MIN / 2 || bounds.y <= i32::MIN / 2 {
2285        return None;
2286    }
2287    Some(bounds)
2288}
2289
2290async fn actions_from_proxies(
2291    proxies: Option<&atspi::proxy::proxy_ext::Proxies<'_>>,
2292) -> Vec<AccessibilityAction> {
2293    let Some(proxies) = proxies else {
2294        return Vec::new();
2295    };
2296    let Ok(action_proxy) = proxies.action().await else {
2297        return Vec::new();
2298    };
2299
2300    read_actions(&action_proxy)
2301        .await
2302        .unwrap_or_default()
2303        .into_iter()
2304        .enumerate()
2305        .map(|(index, action)| AccessibilityAction {
2306            index: index as i32,
2307            name: action.name,
2308            description: action.description,
2309            keybinding: action.keybinding,
2310        })
2311        .collect()
2312}
2313
2314async fn read_actions(proxy: &ActionProxy<'_>) -> Result<Vec<atspi::Action>> {
2315    // WebKit can advertise GetActions without replying to it. The indexed
2316    // methods work, and must also be used when revalidating a cached action.
2317    // Keep the wire spelling: the current atspi binding asks for "Nactions".
2318    timeout(ACTION_QUERY_TIMEOUT, async {
2319        let count = proxy
2320            .inner()
2321            .get_property::<i32>("NActions")
2322            .await
2323            .context("failed to read AT-SPI action count")?;
2324        if count > MAX_ACTIONS_PER_OBJECT {
2325            return Err(anyhow!(
2326                "AT-SPI action count {count} exceeds the {MAX_ACTIONS_PER_OBJECT}-action read budget"
2327            ));
2328        }
2329        if count < 0 {
2330            return Err(anyhow!("invalid negative AT-SPI action count {count}"));
2331        }
2332        Ok(stream::iter(0..count)
2333            .map(|index| async move {
2334                let (name, description, keybinding) = tokio::join!(
2335                    proxy.get_name(index),
2336                    proxy.get_description(index),
2337                    proxy.get_key_binding(index),
2338                );
2339                atspi::Action {
2340                    name: name.unwrap_or_default(),
2341                    description: description.unwrap_or_default(),
2342                    keybinding: keybinding.unwrap_or_default(),
2343                }
2344            })
2345            .buffered(CHILD_READ_CONCURRENCY)
2346            .collect()
2347            .await)
2348    })
2349    .await
2350    .context("AT-SPI action reads exceeded their 5-second deadline")?
2351}
2352
2353async fn states_from_proxy(proxy: &AccessibleProxy<'_>) -> Vec<String> {
2354    proxy
2355        .get_state()
2356        .await
2357        .map(state_labels)
2358        .unwrap_or_default()
2359}
2360
2361async fn value_from_proxies(
2362    proxies: Option<&atspi::proxy::proxy_ext::Proxies<'_>>,
2363) -> Option<AccessibilityValue> {
2364    let value = proxies?.value().await.ok()?;
2365    Some(AccessibilityValue {
2366        current: value.current_value().await.ok()?,
2367        minimum: value.minimum_value().await.ok()?,
2368        maximum: value.maximum_value().await.ok()?,
2369        minimum_increment: value.minimum_increment().await.ok()?,
2370        text: optional_string(value.text().await.ok()),
2371    })
2372}
2373
2374/// `GetNSelections`. The generated proxy method calls `GetNselections`,
2375/// which no toolkit implements, so call the method by its real name.
2376async fn text_selection_count(text: &TextProxy<'_>) -> zbus::Result<i32> {
2377    text.inner()
2378        .call_method("GetNSelections", &())
2379        .await?
2380        .body()
2381        .deserialize()
2382}
2383
2384async fn text_from_proxies(
2385    proxies: Option<&atspi::proxy::proxy_ext::Proxies<'_>>,
2386) -> Option<AccessibilityText> {
2387    let text = proxies?.text().await.ok()?;
2388    let character_count = text.character_count().await.ok()?.max(0);
2389    let caret_offset = text.caret_offset().await.ok();
2390    let capped_count = character_count.min(MAX_TEXT_READBACK_CHARS);
2391    let content = if capped_count > 0 {
2392        optional_string(text.get_text(0, capped_count).await.ok())
2393    } else {
2394        None
2395    };
2396    let selection_count = text_selection_count(&text)
2397        .await
2398        .unwrap_or_default()
2399        .clamp(0, MAX_TEXT_SELECTIONS);
2400    let mut selections = Vec::new();
2401    for index in 0..selection_count {
2402        if let Ok((start_offset, end_offset)) = text.get_selection(index).await {
2403            selections.push(AccessibilityTextSelection {
2404                start_offset,
2405                end_offset,
2406            });
2407        }
2408    }
2409
2410    Some(AccessibilityText {
2411        character_count,
2412        caret_offset,
2413        content,
2414        truncated: character_count > MAX_TEXT_READBACK_CHARS,
2415        selections,
2416    })
2417}
2418
2419async fn supports_editable_text(proxies: Option<&atspi::proxy::proxy_ext::Proxies<'_>>) -> bool {
2420    let Some(proxies) = proxies else {
2421        return false;
2422    };
2423    proxies.editable_text().await.is_ok()
2424}
2425
2426fn state_labels(state_set: StateSet) -> Vec<String> {
2427    state_set.iter().map(|state| state.to_string()).collect()
2428}
2429
2430fn select_action_index(actions: &[atspi::Action], requested_action: Option<&str>) -> Result<i32> {
2431    if actions.is_empty() {
2432        return Err(anyhow!("element exposes no AT-SPI actions"));
2433    }
2434
2435    if let Some(requested_action) = requested_action
2436        .map(str::trim)
2437        .filter(|value| !value.is_empty())
2438    {
2439        let requested_action = requested_action.to_ascii_lowercase();
2440        if let Some((index, _)) = actions.iter().enumerate().find(|(_, action)| {
2441            action.name.to_ascii_lowercase() == requested_action
2442                || action.description.to_ascii_lowercase() == requested_action
2443        }) {
2444            return Ok(index as i32);
2445        }
2446
2447        if let Ok(index) = requested_action.parse::<usize>() {
2448            if index < actions.len() {
2449                return Ok(index as i32);
2450            }
2451        }
2452
2453        return Err(anyhow!(
2454            "requested AT-SPI action was not found; available actions: {}",
2455            actions
2456                .iter()
2457                .map(|action| action.name.as_str())
2458                .collect::<Vec<_>>()
2459                .join(", ")
2460        ));
2461    }
2462
2463    Ok(if actions.len() > 1 { 1 } else { 0 })
2464}
2465
2466fn select_named_action_index(actions: &[atspi::Action], name: &str) -> Result<i32> {
2467    actions
2468        .iter()
2469        .position(|action| action.name.eq_ignore_ascii_case(name))
2470        .map(|index| index as i32)
2471        .ok_or_else(|| {
2472            anyhow!("cached AT-SPI action name is no longer available; refresh get_app_state")
2473        })
2474}
2475
2476fn optional_string(value: Option<String>) -> Option<String> {
2477    value
2478        .map(|value| value.trim().to_string())
2479        .filter(|value| !value.is_empty())
2480}
2481
2482fn object_ref_from_id(object_ref_id: &str) -> Result<ObjectRefOwned> {
2483    let (name, path) = split_object_ref_id(object_ref_id)?;
2484    let name = UniqueName::try_from(name.to_string())
2485        .with_context(|| format!("invalid AT-SPI bus name in object ref {object_ref_id}"))?;
2486    let path = ObjectPath::try_from(path.to_string())
2487        .with_context(|| format!("invalid AT-SPI object path in object ref {object_ref_id}"))?;
2488    Ok(ObjectRef::new_owned(name, path))
2489}
2490
2491fn split_object_ref_id(object_ref_id: &str) -> Result<(&str, &str)> {
2492    let Some(path_start) = object_ref_id.find('/') else {
2493        return Err(anyhow!(
2494            "invalid AT-SPI object ref '{object_ref_id}'; expected ':bus/path'"
2495        ));
2496    };
2497    let (name, path) = object_ref_id.split_at(path_start);
2498    if name.is_empty() || path.is_empty() {
2499        return Err(anyhow!(
2500            "invalid AT-SPI object ref '{object_ref_id}'; expected ':bus/path'"
2501        ));
2502    }
2503    Ok((name, path))
2504}
2505
2506fn object_ref_id(object_ref: &ObjectRefOwned) -> String {
2507    format!(
2508        "{}{}",
2509        object_ref.name_as_str().unwrap_or(""),
2510        object_ref.path_as_str()
2511    )
2512}
2513
2514#[cfg(test)]
2515mod tests {
2516    use super::insert_fixture::*;
2517    use super::*;
2518    use crate::test_sockets::PrivateBus;
2519    use std::sync::{
2520        atomic::{AtomicUsize, Ordering},
2521        Arc, Mutex,
2522    };
2523
2524    const EDITABLE_FIXTURE_PATH: &str = "/editable";
2525
2526    #[derive(Default)]
2527    struct FakeEditableState {
2528        contents: String,
2529        mutations: usize,
2530        character_count_reads: usize,
2531        get_text_reads: usize,
2532        numeric_value: f64,
2533        numeric_writes: usize,
2534    }
2535
2536    #[derive(Clone, Copy)]
2537    enum FakeMutation {
2538        Apply,
2539        NoOp,
2540        Delayed,
2541        Normalize,
2542        Mask,
2543        Reject,
2544        Fail,
2545    }
2546
2547    #[derive(Clone, Copy, Debug)]
2548    enum FakeTextOffsetModel {
2549        UnicodeScalars,
2550        Utf16CodeUnits,
2551    }
2552
2553    #[derive(Clone, Copy)]
2554    enum FakeTextBehavior {
2555        Normal,
2556        CharacterCountError,
2557        GetTextError,
2558        NegativeCount,
2559        StallCharacterCount,
2560    }
2561
2562    #[derive(Clone, Copy)]
2563    struct FakeEditableConfig {
2564        mutation: FakeMutation,
2565        text: FakeTextBehavior,
2566        text_offset_model: FakeTextOffsetModel,
2567        role: atspi::Role,
2568        has_text: bool,
2569        has_value: bool,
2570    }
2571
2572    impl Default for FakeEditableConfig {
2573        fn default() -> Self {
2574            Self {
2575                mutation: FakeMutation::Apply,
2576                text: FakeTextBehavior::Normal,
2577                text_offset_model: FakeTextOffsetModel::Utf16CodeUnits,
2578                role: atspi::Role::Text,
2579                has_text: true,
2580                has_value: false,
2581            }
2582        }
2583    }
2584
2585    struct FakeEditableAccessible(FakeEditableConfig);
2586
2587    #[zbus::interface(name = "org.a11y.atspi.Accessible")]
2588    impl FakeEditableAccessible {
2589        #[zbus(property)]
2590        fn child_count(&self) -> i32 {
2591            0
2592        }
2593
2594        fn get_interfaces(&self) -> Vec<&str> {
2595            let mut interfaces = vec!["org.a11y.atspi.Accessible", "org.a11y.atspi.EditableText"];
2596            if self.0.has_text {
2597                interfaces.push("org.a11y.atspi.Text");
2598            }
2599            if self.0.has_value {
2600                interfaces.push("org.a11y.atspi.Value");
2601            }
2602            interfaces
2603        }
2604
2605        fn get_role(&self) -> atspi::Role {
2606            self.0.role
2607        }
2608    }
2609
2610    struct FakeEditableText {
2611        state: Arc<Mutex<FakeEditableState>>,
2612        mutation: FakeMutation,
2613    }
2614
2615    #[zbus::interface(name = "org.a11y.atspi.EditableText")]
2616    impl FakeEditableText {
2617        fn set_text_contents(&self, new_contents: &str) -> zbus::fdo::Result<bool> {
2618            self.state.lock().unwrap().mutations += 1;
2619            match self.mutation {
2620                FakeMutation::Apply => {
2621                    self.state.lock().unwrap().contents = new_contents.to_string();
2622                }
2623                FakeMutation::NoOp => {}
2624                FakeMutation::Delayed => {
2625                    let state = Arc::clone(&self.state);
2626                    let new_contents = new_contents.to_string();
2627                    tokio::spawn(async move {
2628                        tokio::time::sleep(Duration::from_millis(150)).await;
2629                        state.lock().unwrap().contents = new_contents;
2630                    });
2631                }
2632                FakeMutation::Normalize => {
2633                    self.state.lock().unwrap().contents = new_contents.replace("\r\n", "\n");
2634                }
2635                FakeMutation::Mask => {
2636                    self.state.lock().unwrap().contents = "•".repeat(new_contents.chars().count());
2637                }
2638                FakeMutation::Reject => return Ok(false),
2639                FakeMutation::Fail => {
2640                    return Err(zbus::fdo::Error::Failed(
2641                        "injected SetTextContents failure".into(),
2642                    ));
2643                }
2644            }
2645            Ok(true)
2646        }
2647    }
2648
2649    fn unicode_scalar_offset_to_byte_index(contents: &str, offset: usize) -> Option<usize> {
2650        contents
2651            .char_indices()
2652            .map(|(byte_index, _)| byte_index)
2653            .chain(std::iter::once(contents.len()))
2654            .nth(offset)
2655    }
2656
2657    fn utf16_offset_to_byte_index(contents: &str, offset: usize) -> Option<usize> {
2658        let mut utf16_offset = 0;
2659        for (byte_index, character) in contents.char_indices() {
2660            if utf16_offset == offset {
2661                return Some(byte_index);
2662            }
2663            utf16_offset += character.len_utf16();
2664        }
2665        (utf16_offset == offset).then_some(contents.len())
2666    }
2667
2668    struct FakeText {
2669        state: Arc<Mutex<FakeEditableState>>,
2670        behavior: FakeTextBehavior,
2671        text_offset_model: FakeTextOffsetModel,
2672    }
2673
2674    #[zbus::interface(name = "org.a11y.atspi.Text")]
2675    impl FakeText {
2676        #[zbus(property)]
2677        async fn character_count(&self) -> zbus::fdo::Result<i32> {
2678            self.state.lock().unwrap().character_count_reads += 1;
2679            match self.behavior {
2680                FakeTextBehavior::CharacterCountError => Err(zbus::fdo::Error::Failed(
2681                    "injected CharacterCount failure".into(),
2682                )),
2683                FakeTextBehavior::NegativeCount => Ok(-1),
2684                FakeTextBehavior::StallCharacterCount => std::future::pending().await,
2685                _ => {
2686                    let state = self.state.lock().unwrap();
2687                    let count = match self.text_offset_model {
2688                        FakeTextOffsetModel::UnicodeScalars => state.contents.chars().count(),
2689                        FakeTextOffsetModel::Utf16CodeUnits => {
2690                            state.contents.encode_utf16().count()
2691                        }
2692                    };
2693                    Ok(count as i32)
2694                }
2695            }
2696        }
2697
2698        fn get_text(&self, start_offset: i32, end_offset: i32) -> zbus::fdo::Result<String> {
2699            let mut state = self.state.lock().unwrap();
2700            state.get_text_reads += 1;
2701            if matches!(self.behavior, FakeTextBehavior::GetTextError) {
2702                return Err(zbus::fdo::Error::Failed("injected GetText failure".into()));
2703            }
2704            if start_offset < 0 || end_offset < start_offset {
2705                return Err(zbus::fdo::Error::InvalidArgs("invalid text offsets".into()));
2706            }
2707            let offset_to_byte_index = match self.text_offset_model {
2708                FakeTextOffsetModel::UnicodeScalars => unicode_scalar_offset_to_byte_index,
2709                FakeTextOffsetModel::Utf16CodeUnits => utf16_offset_to_byte_index,
2710            };
2711            let start = offset_to_byte_index(&state.contents, start_offset as usize)
2712                .ok_or_else(|| zbus::fdo::Error::InvalidArgs("invalid text offsets".into()))?;
2713            let end = offset_to_byte_index(&state.contents, end_offset as usize)
2714                .ok_or_else(|| zbus::fdo::Error::InvalidArgs("invalid text offsets".into()))?;
2715            Ok(state.contents[start..end].to_string())
2716        }
2717    }
2718
2719    struct FakeValue(Arc<Mutex<FakeEditableState>>);
2720
2721    #[zbus::interface(name = "org.a11y.atspi.Value")]
2722    impl FakeValue {
2723        #[zbus(property)]
2724        fn current_value(&self) -> f64 {
2725            self.0.lock().unwrap().numeric_value
2726        }
2727
2728        #[zbus(property)]
2729        fn set_current_value(&self, value: f64) {
2730            let mut state = self.0.lock().unwrap();
2731            state.numeric_value = value;
2732            state.numeric_writes += 1;
2733        }
2734    }
2735
2736    async fn start_editable_fixture(
2737        initial_contents: &str,
2738        config: FakeEditableConfig,
2739    ) -> (
2740        PrivateBus,
2741        zbus::Connection,
2742        zbus::Connection,
2743        Arc<Mutex<FakeEditableState>>,
2744    ) {
2745        let bus = PrivateBus::start("cul-atspi-bus");
2746        let address = bus.address();
2747        let state = Arc::new(Mutex::new(FakeEditableState {
2748            contents: initial_contents.to_string(),
2749            ..Default::default()
2750        }));
2751        let mut builder = zbus::connection::Builder::address(address)
2752            .unwrap()
2753            .serve_at(EDITABLE_FIXTURE_PATH, FakeEditableAccessible(config))
2754            .unwrap()
2755            .serve_at(
2756                EDITABLE_FIXTURE_PATH,
2757                FakeEditableText {
2758                    state: Arc::clone(&state),
2759                    mutation: config.mutation,
2760                },
2761            )
2762            .unwrap();
2763        if config.has_text {
2764            builder = builder
2765                .serve_at(
2766                    EDITABLE_FIXTURE_PATH,
2767                    FakeText {
2768                        state: Arc::clone(&state),
2769                        behavior: config.text,
2770                        text_offset_model: config.text_offset_model,
2771                    },
2772                )
2773                .unwrap();
2774        }
2775        if config.has_value {
2776            builder = builder
2777                .serve_at(EDITABLE_FIXTURE_PATH, FakeValue(Arc::clone(&state)))
2778                .unwrap();
2779        }
2780        let peer = builder.build().await.unwrap();
2781        let client = zbus::connection::Builder::address(address)
2782            .unwrap()
2783            .build()
2784            .await
2785            .unwrap();
2786        (bus, peer, client, state)
2787    }
2788
2789    async fn dispatch_editable_fixture(
2790        client: &zbus::Connection,
2791        peer: &zbus::Connection,
2792        value: &str,
2793    ) -> Result<ValueSetInvocation> {
2794        let proxy = AccessibleProxy::builder(client)
2795            .destination(peer.unique_name().unwrap().clone())
2796            .unwrap()
2797            .path(EDITABLE_FIXTURE_PATH)
2798            .unwrap()
2799            .cache_properties(zbus::proxy::CacheProperties::No)
2800            .build()
2801            .await
2802            .unwrap();
2803        let proxies = proxy.proxies().await.unwrap();
2804        set_element_value_with_proxies(&proxy, &proxies, value).await
2805    }
2806
2807    fn editable_outcome(invocation: ValueSetInvocation) -> EditableTextSetOutcome {
2808        match invocation {
2809            ValueSetInvocation::EditableText { outcome } => outcome,
2810            ValueSetInvocation::Numeric { .. } => panic!("expected editable-text dispatch"),
2811        }
2812    }
2813
2814    struct FakeAccessible {
2815        name: String,
2816        children: Vec<(String, OwnedObjectPath)>,
2817        has_action: bool,
2818    }
2819
2820    #[zbus::interface(name = "org.a11y.atspi.Accessible")]
2821    impl FakeAccessible {
2822        #[zbus(property)]
2823        fn child_count(&self) -> i32 {
2824            self.children.len() as i32
2825        }
2826
2827        #[zbus(property)]
2828        fn name(&self) -> &str {
2829            &self.name
2830        }
2831
2832        fn get_interfaces(&self) -> Vec<&str> {
2833            let mut interfaces = vec!["org.a11y.atspi.Accessible"];
2834            if self.has_action {
2835                interfaces.push("org.a11y.atspi.Action");
2836            }
2837            interfaces
2838        }
2839
2840        fn get_child_at_index(
2841            &self,
2842            index: i32,
2843        ) -> zbus::fdo::Result<((String, OwnedObjectPath),)> {
2844            self.children
2845                .get(index as usize)
2846                .cloned()
2847                .map(|child| (child,))
2848                .ok_or_else(|| zbus::fdo::Error::InvalidArgs("invalid child index".into()))
2849        }
2850    }
2851
2852    struct FakeWebKitAction {
2853        count: i32,
2854        stall_indexed_reads: bool,
2855        name_reads: Arc<AtomicUsize>,
2856    }
2857
2858    impl Default for FakeWebKitAction {
2859        fn default() -> Self {
2860            Self {
2861                count: 1,
2862                stall_indexed_reads: false,
2863                name_reads: Arc::default(),
2864            }
2865        }
2866    }
2867
2868    #[zbus::interface(name = "org.a11y.atspi.Action")]
2869    impl FakeWebKitAction {
2870        async fn get_actions(&self) -> Vec<atspi::Action> {
2871            std::future::pending().await
2872        }
2873
2874        #[zbus(property, name = "NActions")]
2875        fn nactions(&self) -> i32 {
2876            self.count
2877        }
2878
2879        async fn get_name(&self, index: i32) -> &str {
2880            assert!((0..self.count).contains(&index));
2881            self.name_reads.fetch_add(1, Ordering::SeqCst);
2882            if self.stall_indexed_reads {
2883                std::future::pending::<()>().await;
2884            }
2885            "click"
2886        }
2887
2888        async fn get_localized_name(&self, index: i32) -> &str {
2889            assert!((0..self.count).contains(&index));
2890            "Activate"
2891        }
2892
2893        fn get_description(&self, index: i32) -> &str {
2894            assert!((0..self.count).contains(&index));
2895            "Activate the control"
2896        }
2897
2898        fn get_key_binding(&self, index: i32) -> &str {
2899            assert!((0..self.count).contains(&index));
2900            "Return"
2901        }
2902
2903        fn do_action(&self, index: i32) -> bool {
2904            index == 0
2905        }
2906    }
2907
2908    struct FakeQtAction;
2909
2910    #[zbus::interface(name = "org.a11y.atspi.Action")]
2911    impl FakeQtAction {
2912        #[zbus(property, name = "NActions")]
2913        fn nactions(&self) -> i32 {
2914            2
2915        }
2916
2917        fn get_name(&self, index: i32) -> &str {
2918            match index {
2919                0 => "Press",
2920                1 => "Set Focus",
2921                _ => panic!("invalid action index"),
2922            }
2923        }
2924
2925        fn get_description(&self, index: i32) -> &str {
2926            match index {
2927                0 => "Eylemi tetikler",
2928                1 => "Odağı ayarlar",
2929                _ => panic!("invalid action index"),
2930            }
2931        }
2932
2933        fn get_key_binding(&self, _index: i32) -> &str {
2934            ""
2935        }
2936    }
2937
2938    #[tokio::test]
2939    async fn editable_text_true_without_publication_is_mismatch_and_mutates_once() {
2940        let (_bus, peer, client, state) = start_editable_fixture(
2941            "original",
2942            FakeEditableConfig {
2943                mutation: FakeMutation::NoOp,
2944                ..Default::default()
2945            },
2946        )
2947        .await;
2948
2949        let outcome = editable_outcome(
2950            dispatch_editable_fixture(&client, &peer, "modified")
2951                .await
2952                .unwrap(),
2953        );
2954
2955        // A last poll can cross the same fixed deadline. Both outcomes mean
2956        // an unverified write; neither permits verification or replay.
2957        assert!(
2958            matches!(
2959                outcome,
2960                EditableTextSetOutcome::MismatchAfterDeadline
2961                    | EditableTextSetOutcome::ReadbackTimedOut
2962            ),
2963            "{outcome:?}"
2964        );
2965        let state = state.lock().unwrap();
2966        assert_eq!(state.mutations, 1);
2967        assert!(state.character_count_reads > 1);
2968        assert!(state.get_text_reads > 1);
2969        assert_eq!(state.contents, "original");
2970    }
2971
2972    #[tokio::test]
2973    async fn editable_text_exact_readback_accepts_empty_whitespace_and_trailing_newline() {
2974        let (_bus, peer, client, state) =
2975            start_editable_fixture("initial", FakeEditableConfig::default()).await;
2976        let values = [
2977            "",
2978            " \t\n",
2979            "  leading and trailing\t \n",
2980            "trailing newline\n",
2981            "Case and unicode € 内容 😀🦀𐐷",
2982        ];
2983
2984        for value in values {
2985            let outcome = editable_outcome(
2986                dispatch_editable_fixture(&client, &peer, value)
2987                    .await
2988                    .unwrap(),
2989            );
2990            assert_eq!(outcome, EditableTextSetOutcome::Verified);
2991            assert_eq!(state.lock().unwrap().contents, value);
2992        }
2993        assert_eq!(state.lock().unwrap().mutations, values.len());
2994    }
2995
2996    #[tokio::test]
2997    async fn editable_text_non_bmp_readback_supports_scalar_and_utf16_peers() {
2998        let requested = "🦀 GTK verified ";
2999        for text_offset_model in [
3000            FakeTextOffsetModel::UnicodeScalars,
3001            FakeTextOffsetModel::Utf16CodeUnits,
3002        ] {
3003            let (_bus, peer, client, state) = start_editable_fixture(
3004                "",
3005                FakeEditableConfig {
3006                    text_offset_model,
3007                    ..Default::default()
3008                },
3009            )
3010            .await;
3011
3012            let outcome = editable_outcome(
3013                dispatch_editable_fixture(&client, &peer, requested)
3014                    .await
3015                    .unwrap(),
3016            );
3017
3018            assert_eq!(
3019                outcome,
3020                EditableTextSetOutcome::Verified,
3021                "{text_offset_model:?}"
3022            );
3023            let state = state.lock().unwrap();
3024            assert_eq!(state.mutations, 1);
3025            assert_eq!(state.contents, requested);
3026        }
3027    }
3028
3029    #[tokio::test]
3030    async fn editable_text_non_bmp_matching_count_does_not_accept_different_content() {
3031        let requested = "🦀 GTK verified ";
3032        let published = "🦀 GTK verified!";
3033        assert_eq!(requested.chars().count(), published.chars().count());
3034        assert_eq!(
3035            requested.encode_utf16().count(),
3036            published.encode_utf16().count()
3037        );
3038        for text_offset_model in [
3039            FakeTextOffsetModel::UnicodeScalars,
3040            FakeTextOffsetModel::Utf16CodeUnits,
3041        ] {
3042            let (_bus, peer, client, state) = start_editable_fixture(
3043                published,
3044                FakeEditableConfig {
3045                    mutation: FakeMutation::NoOp,
3046                    text_offset_model,
3047                    ..Default::default()
3048                },
3049            )
3050            .await;
3051
3052            let outcome = editable_outcome(
3053                dispatch_editable_fixture(&client, &peer, requested)
3054                    .await
3055                    .unwrap(),
3056            );
3057
3058            // A last poll can cross the same fixed deadline. Both outcomes
3059            // leave the write unverified without extending its deadline.
3060            assert!(
3061                matches!(
3062                    outcome,
3063                    EditableTextSetOutcome::MismatchAfterDeadline
3064                        | EditableTextSetOutcome::ReadbackTimedOut
3065                ),
3066                "{text_offset_model:?}: {outcome:?}"
3067            );
3068            let state = state.lock().unwrap();
3069            assert_eq!(state.mutations, 1);
3070            assert!(state.get_text_reads > 0, "{text_offset_model:?}");
3071            assert_eq!(state.contents, published);
3072        }
3073    }
3074
3075    #[tokio::test]
3076    async fn editable_text_readback_chunks_utf16_without_splitting_non_bmp() {
3077        let (_bus, peer, client, state) = start_editable_fixture(
3078            "",
3079            FakeEditableConfig {
3080                text_offset_model: FakeTextOffsetModel::Utf16CodeUnits,
3081                ..Default::default()
3082            },
3083        )
3084        .await;
3085        let mut expected = "a".repeat(EDITABLE_TEXT_READ_CHUNK_UNITS - 1);
3086        // The crab's surrogate pair straddles the first 4096-unit read boundary.
3087        expected.push_str("🦀é");
3088        expected.push_str(&"内容\n".repeat(1_200));
3089        assert!(expected.encode_utf16().count() > MAX_TEXT_READBACK_CHARS as usize);
3090
3091        let outcome = editable_outcome(
3092            dispatch_editable_fixture(&client, &peer, &expected)
3093                .await
3094                .unwrap(),
3095        );
3096
3097        assert_eq!(outcome, EditableTextSetOutcome::Verified);
3098        let state = state.lock().unwrap();
3099        assert_eq!(state.mutations, 1);
3100        assert!(state.get_text_reads >= 2);
3101        assert_eq!(state.contents, expected);
3102    }
3103
3104    #[tokio::test]
3105    async fn editable_text_readback_waits_for_async_publication() {
3106        let (_bus, peer, client, state) = start_editable_fixture(
3107            "pending",
3108            FakeEditableConfig {
3109                mutation: FakeMutation::Delayed,
3110                ..Default::default()
3111            },
3112        )
3113        .await;
3114
3115        let outcome = editable_outcome(
3116            dispatch_editable_fixture(&client, &peer, "published asynchronously")
3117                .await
3118                .unwrap(),
3119        );
3120
3121        assert_eq!(outcome, EditableTextSetOutcome::Verified);
3122        let state = state.lock().unwrap();
3123        assert_eq!(state.mutations, 1);
3124        assert!(state.character_count_reads > 1);
3125        assert_eq!(state.contents, "published asynchronously");
3126    }
3127
3128    #[tokio::test]
3129    async fn editable_text_normalization_mismatch_is_not_verified() {
3130        let (_bus, peer, client, state) = start_editable_fixture(
3131            "",
3132            FakeEditableConfig {
3133                mutation: FakeMutation::Normalize,
3134                ..Default::default()
3135            },
3136        )
3137        .await;
3138
3139        let outcome = editable_outcome(
3140            dispatch_editable_fixture(&client, &peer, "first\r\nsecond\n")
3141                .await
3142                .unwrap(),
3143        );
3144
3145        // A last poll can cross the same fixed deadline. Both outcomes mean
3146        // an unverified write; neither permits verification or replay.
3147        assert!(
3148            matches!(
3149                outcome,
3150                EditableTextSetOutcome::MismatchAfterDeadline
3151                    | EditableTextSetOutcome::ReadbackTimedOut
3152            ),
3153            "{outcome:?}"
3154        );
3155        let state = state.lock().unwrap();
3156        assert_eq!(state.mutations, 1);
3157        assert!(state.character_count_reads > 1);
3158        assert_eq!(state.contents, "first\nsecond\n");
3159    }
3160
3161    #[tokio::test]
3162    async fn password_text_is_unverifiable_even_when_requested_text_is_bullets() {
3163        let (_bus, peer, client, state) = start_editable_fixture(
3164            "",
3165            FakeEditableConfig {
3166                mutation: FakeMutation::Mask,
3167                role: atspi::Role::PasswordText,
3168                ..Default::default()
3169            },
3170        )
3171        .await;
3172
3173        let outcome = editable_outcome(
3174            dispatch_editable_fixture(&client, &peer, "••••••••")
3175                .await
3176                .unwrap(),
3177        );
3178
3179        assert_eq!(outcome, EditableTextSetOutcome::PasswordUnverifiable);
3180        let state = state.lock().unwrap();
3181        assert_eq!(state.mutations, 1);
3182        assert_eq!(state.character_count_reads, 0);
3183        assert_eq!(state.contents, "••••••••");
3184    }
3185
3186    #[tokio::test]
3187    async fn editable_text_missing_text_and_read_errors_are_structured_outcomes() {
3188        let configs = [
3189            FakeEditableConfig {
3190                has_text: false,
3191                ..Default::default()
3192            },
3193            FakeEditableConfig {
3194                text: FakeTextBehavior::CharacterCountError,
3195                ..Default::default()
3196            },
3197            FakeEditableConfig {
3198                text: FakeTextBehavior::GetTextError,
3199                ..Default::default()
3200            },
3201        ];
3202
3203        for config in configs {
3204            let (_bus, peer, client, state) = start_editable_fixture("before", config).await;
3205            let outcome = editable_outcome(
3206                dispatch_editable_fixture(&client, &peer, "readback may have changed")
3207                    .await
3208                    .unwrap(),
3209            );
3210            assert_eq!(outcome, EditableTextSetOutcome::ReadbackFailed);
3211            assert_eq!(state.lock().unwrap().mutations, 1);
3212        }
3213    }
3214
3215    #[tokio::test]
3216    async fn editable_text_negative_counts_and_stalled_readback_are_structured_outcomes() {
3217        let cases = [
3218            (
3219                FakeTextBehavior::NegativeCount,
3220                EditableTextSetOutcome::ReadbackFailed,
3221            ),
3222            (
3223                FakeTextBehavior::StallCharacterCount,
3224                EditableTextSetOutcome::ReadbackTimedOut,
3225            ),
3226        ];
3227
3228        for (text, expected) in cases {
3229            let (_bus, peer, client, state) = start_editable_fixture(
3230                "before",
3231                FakeEditableConfig {
3232                    text,
3233                    ..Default::default()
3234                },
3235            )
3236            .await;
3237            let outcome = editable_outcome(
3238                dispatch_editable_fixture(&client, &peer, "after")
3239                    .await
3240                    .unwrap(),
3241            );
3242            assert_eq!(outcome, expected);
3243            let state = state.lock().unwrap();
3244            assert_eq!(state.mutations, 1);
3245            assert_eq!(state.get_text_reads, 0);
3246        }
3247    }
3248
3249    #[tokio::test]
3250    async fn editable_text_rejection_and_mutation_errors_remain_errors() {
3251        let cases = [
3252            (FakeMutation::Reject, "rejected"),
3253            (FakeMutation::Fail, "failed to set"),
3254        ];
3255
3256        for (mutation, expected_error) in cases {
3257            let (_bus, peer, client, state) = start_editable_fixture(
3258                "before",
3259                FakeEditableConfig {
3260                    mutation,
3261                    ..Default::default()
3262                },
3263            )
3264            .await;
3265            let error = dispatch_editable_fixture(&client, &peer, "after")
3266                .await
3267                .unwrap_err();
3268            assert!(error.to_string().contains(expected_error));
3269            let state = state.lock().unwrap();
3270            assert_eq!(state.mutations, 1);
3271            assert_eq!(state.character_count_reads, 0);
3272        }
3273    }
3274
3275    #[tokio::test]
3276    async fn numeric_value_dispatch_remains_isolated_from_editable_text() {
3277        let (_bus, peer, client, state) = start_editable_fixture(
3278            "unchanged",
3279            FakeEditableConfig {
3280                has_value: true,
3281                ..Default::default()
3282            },
3283        )
3284        .await;
3285
3286        let invocation = dispatch_editable_fixture(&client, &peer, "42.5")
3287            .await
3288            .unwrap();
3289
3290        match invocation {
3291            ValueSetInvocation::Numeric { value } => assert_eq!(value, 42.5),
3292            ValueSetInvocation::EditableText { .. } => panic!("expected numeric dispatch"),
3293        }
3294        let state = state.lock().unwrap();
3295        assert_eq!(state.numeric_value, 42.5);
3296        assert_eq!(state.numeric_writes, 1);
3297        assert_eq!(state.mutations, 0);
3298        assert_eq!(state.character_count_reads, 0);
3299        assert_eq!(state.contents, "unchanged");
3300    }
3301
3302    #[tokio::test]
3303    async fn qt_action_names_do_not_depend_on_localized_names() {
3304        let bus = PrivateBus::start("cul-atspi-bus");
3305        let address = bus.address();
3306        let peer = zbus::connection::Builder::address(address)
3307            .unwrap()
3308            .serve_at("/actions/qt", FakeQtAction)
3309            .unwrap()
3310            .build()
3311            .await
3312            .unwrap();
3313        let client = zbus::connection::Builder::address(address)
3314            .unwrap()
3315            .build()
3316            .await
3317            .unwrap();
3318        let action = ActionProxy::builder(&client)
3319            .destination(peer.unique_name().unwrap().clone())
3320            .unwrap()
3321            .path("/actions/qt")
3322            .unwrap()
3323            .cache_properties(zbus::proxy::CacheProperties::No)
3324            .build()
3325            .await
3326            .unwrap();
3327
3328        let actions = timeout(Duration::from_secs(1), read_actions(&action))
3329            .await
3330            .expect("Qt action reads must not require GetLocalizedName")
3331            .unwrap();
3332
3333        assert_eq!(actions.len(), 2);
3334        assert_eq!(actions[0].name, "Press");
3335        assert_eq!(actions[0].description, "Eylemi tetikler");
3336        assert_eq!(actions[1].name, "Set Focus");
3337        assert_eq!(actions[1].description, "Odağı ayarlar");
3338        assert_eq!(select_named_action_index(&actions, "press").unwrap(), 0);
3339    }
3340
3341    #[tokio::test]
3342    async fn pid_roots_keep_all_toolkits_and_a_missing_pid_stays_empty() {
3343        let bus = PrivateBus::start("cul-atspi-roots");
3344        let root_path = "/org/a11y/atspi/accessible/root";
3345        let mut peers = Vec::new();
3346        for child_count in [0, 1] {
3347            let children = (0..child_count)
3348                .map(|_| (String::new(), "/child".try_into().unwrap()))
3349                .collect();
3350            peers.push(
3351                zbus::connection::Builder::address(bus.address())
3352                    .unwrap()
3353                    .serve_at(
3354                        root_path,
3355                        FakeAccessible {
3356                            name: "qt-app".into(),
3357                            children,
3358                            has_action: false,
3359                        },
3360                    )
3361                    .unwrap()
3362                    .build()
3363                    .await
3364                    .unwrap(),
3365            );
3366        }
3367        let conn = AccessibilityConnection::from_address(bus.address().parse().unwrap())
3368            .await
3369            .unwrap();
3370        let roots = peers
3371            .iter()
3372            .map(|peer| {
3373                object_ref_from_id(&format!("{}{root_path}", peer.unique_name().unwrap())).unwrap()
3374            })
3375            .collect::<Vec<_>>();
3376        let pid = std::process::id();
3377        let mut budget = MAX_DISCOVERY_CHILD_READS;
3378        let selected = select_roots(&conn, roots.clone(), None, Some(pid), None, &mut budget).await;
3379        assert_eq!(selected.roots, roots);
3380        assert_eq!(selected.pid, Some(pid));
3381        assert!(selected.scoped);
3382        assert!(selected.app_filter_matched);
3383
3384        let explicit = object_ref_id(&roots[1]);
3385        let selected = select_roots(
3386            &conn,
3387            roots.clone(),
3388            Some(&explicit),
3389            Some(pid),
3390            None,
3391            &mut budget,
3392        )
3393        .await;
3394        assert_eq!(selected.roots, vec![roots[1].clone()]);
3395        assert_eq!(selected.pid, Some(pid));
3396        assert!(selected.app_filter_matched);
3397
3398        let selected = select_roots(
3399            &conn,
3400            roots.clone(),
3401            None,
3402            Some(u32::MAX),
3403            None,
3404            &mut budget,
3405        )
3406        .await;
3407        assert!(selected.roots.is_empty());
3408        assert_eq!(selected.pid, None);
3409        assert!(selected.scoped);
3410        assert!(!selected.app_filter_matched);
3411
3412        // A listed window whose pid owns no root (a Flatpak app behind
3413        // xdg-dbus-proxy) finds the root by name. No pid is recorded.
3414        let selected = select_roots(
3415            &conn,
3416            roots.clone(),
3417            None,
3418            Some(u32::MAX),
3419            Some("qt-app"),
3420            &mut budget,
3421        )
3422        .await;
3423        assert_eq!(selected.roots, roots);
3424        assert_eq!(selected.pid, None);
3425        assert!(selected.scoped);
3426        assert!(selected.app_filter_matched);
3427
3428        // The name is a fallback only: the pid's own roots win.
3429        let selected = select_roots(
3430            &conn,
3431            roots.clone(),
3432            None,
3433            Some(pid),
3434            Some("no such window"),
3435            &mut budget,
3436        )
3437        .await;
3438        assert_eq!(selected.roots, roots);
3439        assert_eq!(selected.pid, Some(pid));
3440
3441        let selected = select_roots(
3442            &conn,
3443            roots,
3444            None,
3445            Some(u32::MAX),
3446            Some("no such window"),
3447            &mut budget,
3448        )
3449        .await;
3450        assert!(selected.roots.is_empty());
3451        assert!(!selected.app_filter_matched);
3452    }
3453
3454    #[tokio::test]
3455    async fn indexed_children_resolve_webkit_names_on_the_accessibility_bus() {
3456        let bus = PrivateBus::start("cul-atspi-bus");
3457        let address = bus.address();
3458
3459        let webkit_name = "org.webkit.MockWebProcess";
3460        let child_path = "/org/a11y/webkit/accessible/child";
3461        let webkit = zbus::connection::Builder::address(address)
3462            .unwrap()
3463            .name(webkit_name)
3464            .unwrap()
3465            .serve_at(
3466                child_path,
3467                FakeAccessible {
3468                    name: "WebKit page".into(),
3469                    children: Vec::new(),
3470                    has_action: true,
3471                },
3472            )
3473            .unwrap()
3474            .serve_at(child_path, FakeWebKitAction::default())
3475            .unwrap()
3476            .build()
3477            .await
3478            .unwrap();
3479        let owner = webkit.unique_name().unwrap().to_string();
3480        let gtk = zbus::connection::Builder::address(address)
3481            .unwrap()
3482            .serve_at(
3483                "/org/a11y/atspi/accessible/root",
3484                FakeAccessible {
3485                    name: "GTK socket".into(),
3486                    has_action: false,
3487                    children: vec![
3488                        (webkit_name.into(), child_path.try_into().unwrap()),
3489                        (owner.clone(), child_path.try_into().unwrap()),
3490                        (String::new(), "/org/a11y/atspi/null".try_into().unwrap()),
3491                        (
3492                            "org.webkit.UnownedWebProcess".into(),
3493                            child_path.try_into().unwrap(),
3494                        ),
3495                    ],
3496                },
3497            )
3498            .unwrap()
3499            .build()
3500            .await
3501            .unwrap();
3502        let client = zbus::connection::Builder::address(address)
3503            .unwrap()
3504            .build()
3505            .await
3506            .unwrap();
3507        let proxy = AccessibleProxy::builder(&client)
3508            .destination(gtk.unique_name().unwrap().clone())
3509            .unwrap()
3510            .path("/org/a11y/atspi/accessible/root")
3511            .unwrap()
3512            .build()
3513            .await
3514            .unwrap();
3515        let mut remaining = 4;
3516        let reply = proxy
3517            .inner()
3518            .call_method("GetChildAtIndex", &(0_i32,))
3519            .await
3520            .unwrap();
3521        assert_eq!(reply.body().signature().to_string(), "(so)");
3522        let batch = children_up_to(&proxy, 4, &mut remaining).await.unwrap();
3523
3524        assert_eq!(batch.attempted, 4);
3525        assert_eq!(remaining, 0);
3526        assert!(!batch.incomplete);
3527        assert_eq!(batch.items.len(), 3, "only the unowned name should fail");
3528        assert_eq!(batch.items[0].name_as_str(), Some(owner.as_str()));
3529        assert_eq!(batch.items[0].path_as_str(), child_path);
3530        assert_eq!(batch.items[0], batch.items[1]);
3531        assert!(batch.items[2].is_null());
3532
3533        // The canonical reference remains usable by the normal read/action path.
3534        let child = batch.items[0].as_accessible_proxy(&client).await.unwrap();
3535        assert_eq!(child.name().await.unwrap(), "WebKit page");
3536        assert_eq!(
3537            object_ref_from_id(&object_ref_id(&batch.items[0])).unwrap(),
3538            batch.items[0]
3539        );
3540        let action = child.proxies().await.unwrap().action().await.unwrap();
3541        let actions = timeout(Duration::from_secs(1), read_actions(&action))
3542            .await
3543            .expect("indexed action reads must not wait for GetActions")
3544            .unwrap();
3545        assert_eq!(actions.len(), 1);
3546        assert_eq!(actions[0].name, "click");
3547        assert_eq!(actions[0].description, "Activate the control");
3548        assert_eq!(actions[0].keybinding, "Return");
3549        assert_eq!(select_named_action_index(&actions, "click").unwrap(), 0);
3550        assert!(action.do_action(0).await.unwrap());
3551    }
3552
3553    #[tokio::test]
3554    async fn indexed_actions_bound_untrusted_counts_before_reading_indices() {
3555        let bus = PrivateBus::start("cul-atspi-bus");
3556        let address = bus.address();
3557        let name_reads = Arc::new(AtomicUsize::new(0));
3558        let counts = [
3559            -1,
3560            MAX_ACTIONS_PER_OBJECT + 1,
3561            i32::MAX,
3562            0,
3563            MAX_ACTIONS_PER_OBJECT,
3564        ];
3565        let mut builder = zbus::connection::Builder::address(address).unwrap();
3566        for (index, count) in counts.iter().enumerate() {
3567            builder = builder
3568                .serve_at(
3569                    format!("/actions/{index}"),
3570                    FakeWebKitAction {
3571                        count: *count,
3572                        name_reads: Arc::clone(&name_reads),
3573                        ..Default::default()
3574                    },
3575                )
3576                .unwrap();
3577        }
3578        let peer = builder.build().await.unwrap();
3579        let client = zbus::connection::Builder::address(address)
3580            .unwrap()
3581            .build()
3582            .await
3583            .unwrap();
3584
3585        for (index, count) in counts.iter().enumerate() {
3586            let action = ActionProxy::builder(&client)
3587                .destination(peer.unique_name().unwrap().clone())
3588                .unwrap()
3589                .path(format!("/actions/{index}"))
3590                .unwrap()
3591                .cache_properties(zbus::proxy::CacheProperties::No)
3592                .build()
3593                .await
3594                .unwrap();
3595            let result = timeout(Duration::from_secs(1), read_actions(&action))
3596                .await
3597                .expect("untrusted counts must not cause unbounded work");
3598            if (0..=MAX_ACTIONS_PER_OBJECT).contains(count) {
3599                assert_eq!(result.unwrap().len(), *count as usize);
3600            } else {
3601                let error = result.unwrap_err().to_string();
3602                assert!(error.contains("action count"), "{error}");
3603                assert_eq!(name_reads.load(Ordering::SeqCst), 0);
3604            }
3605        }
3606        assert_eq!(
3607            name_reads.load(Ordering::SeqCst),
3608            MAX_ACTIONS_PER_OBJECT as usize
3609        );
3610    }
3611
3612    #[tokio::test]
3613    async fn indexed_actions_time_out_the_entire_read() {
3614        let bus = PrivateBus::start("cul-atspi-bus");
3615        let address = bus.address();
3616        let name_reads = Arc::new(AtomicUsize::new(0));
3617        let peer = zbus::connection::Builder::address(address)
3618            .unwrap()
3619            .serve_at(
3620                "/actions/stalled",
3621                FakeWebKitAction {
3622                    stall_indexed_reads: true,
3623                    name_reads: Arc::clone(&name_reads),
3624                    ..Default::default()
3625                },
3626            )
3627            .unwrap()
3628            .build()
3629            .await
3630            .unwrap();
3631        let client = zbus::connection::Builder::address(address)
3632            .unwrap()
3633            .build()
3634            .await
3635            .unwrap();
3636        let action = ActionProxy::builder(&client)
3637            .destination(peer.unique_name().unwrap().clone())
3638            .unwrap()
3639            .path("/actions/stalled")
3640            .unwrap()
3641            .cache_properties(zbus::proxy::CacheProperties::No)
3642            .build()
3643            .await
3644            .unwrap();
3645
3646        let error = timeout(
3647            ACTION_QUERY_TIMEOUT + Duration::from_secs(1),
3648            read_actions(&action),
3649        )
3650        .await
3651        .expect("indexed reads must have an overall deadline")
3652        .unwrap_err();
3653        assert!(error.to_string().contains("5-second deadline"));
3654        assert_eq!(name_reads.load(Ordering::SeqCst), 1);
3655    }
3656
3657    fn app_children(children: &[(&str, &str)]) -> Vec<(String, Option<String>)> {
3658        children
3659            .iter()
3660            .map(|(role, name)| (role.to_string(), Some(name.to_string())))
3661            .collect()
3662    }
3663
3664    #[test]
3665    fn a_window_title_picks_one_of_several_app_windows() {
3666        let chromium = app_children(&[
3667            ("frame", "GitHub - Chromium"),
3668            ("frame", "PlanetScale - Chromium"),
3669            ("menu", ""),
3670        ]);
3671        assert_eq!(
3672            matching_window(&chromium, "PlanetScale - Chromium"),
3673            Some(1)
3674        );
3675        assert_eq!(
3676            matching_window(&chromium, "planetscale - chromium"),
3677            Some(1)
3678        );
3679        // A title substring, as a caller passes it.
3680        assert_eq!(matching_window(&chromium, "PlanetScale"), Some(1));
3681        // Matches every window: keep them all.
3682        assert_eq!(matching_window(&chromium, "Chromium"), None);
3683        assert_eq!(matching_window(&chromium, "Gmail"), None);
3684    }
3685
3686    #[test]
3687    fn a_decorated_compositor_title_picks_the_frame_it_decorates() {
3688        let chromium = app_children(&[
3689            ("frame", "GitHub - Chromium"),
3690            ("frame", "PlanetScale - Chromium"),
3691        ]);
3692        assert_eq!(
3693            matching_window(&chromium, "PlanetScale - Chromium (Profile 1)"),
3694            Some(1)
3695        );
3696        // Both names are decorated prefixes: the longest wins.
3697        let nested = app_children(&[("frame", "Docs"), ("frame", "Docs - Settings")]);
3698        assert_eq!(
3699            matching_window(&nested, "Docs - Settings (Profile 1)"),
3700            Some(1)
3701        );
3702        // A name inside the title but not its prefix is not a decoration.
3703        let generic = app_children(&[("frame", "Settings"), ("frame", "Mail")]);
3704        assert_eq!(
3705            matching_window(&generic, "Docs - Settings (Profile 1)"),
3706            None
3707        );
3708        assert_eq!(matching_window(&generic, "Mailbox"), None);
3709    }
3710
3711    #[test]
3712    fn an_exact_window_name_wins_over_a_substring_match() {
3713        let windows = app_children(&[("frame", "Docs"), ("frame", "Docs - Settings")]);
3714        assert_eq!(matching_window(&windows, "Docs"), Some(0));
3715    }
3716
3717    #[test]
3718    fn narrowing_keeps_popups_and_dialogs_beside_the_window() {
3719        let chromium = app_children(&[
3720            ("frame", "GitHub - Chromium"),
3721            ("frame", "PlanetScale - Chromium"),
3722            ("window", ""),
3723            ("dialog", "Open File"),
3724            ("menu", ""),
3725        ]);
3726        let chosen = matching_window(&chromium, "PlanetScale").unwrap();
3727        assert_eq!(
3728            kept_beside_window(&chromium, chosen),
3729            [false, true, true, true, true]
3730        );
3731    }
3732
3733    #[test]
3734    fn one_window_is_never_narrowed() {
3735        let single = app_children(&[("frame", "PlanetScale - Chromium"), ("menu", "")]);
3736        assert_eq!(matching_window(&single, "PlanetScale"), None);
3737    }
3738
3739    #[test]
3740    fn split_object_ref_id_separates_bus_name_and_path() {
3741        let (name, path) = split_object_ref_id(":1.42/org/a11y/atspi/accessible/7").unwrap();
3742
3743        assert_eq!(name, ":1.42");
3744        assert_eq!(path, "/org/a11y/atspi/accessible/7");
3745    }
3746
3747    #[test]
3748    fn select_action_index_uses_named_action() {
3749        let actions = vec![
3750            atspi::Action {
3751                name: "click".to_string(),
3752                description: "Clicks".to_string(),
3753                keybinding: String::new(),
3754            },
3755            atspi::Action {
3756                name: "show-menu".to_string(),
3757                description: "Shows menu".to_string(),
3758                keybinding: String::new(),
3759            },
3760        ];
3761
3762        assert_eq!(select_action_index(&actions, Some("show-menu")).unwrap(), 1);
3763    }
3764
3765    #[test]
3766    fn cached_action_name_is_revalidated_against_current_actions() {
3767        let mut actions = vec![atspi::Action {
3768            name: "show-menu".into(),
3769            description: "Click".into(),
3770            keybinding: String::new(),
3771        }];
3772        // Neither a stale index nor a matching description may invoke another action.
3773        assert!(select_named_action_index(&actions, "Click").is_err());
3774        actions.push(atspi::Action {
3775            name: "click".into(),
3776            description: String::new(),
3777            keybinding: String::new(),
3778        });
3779        assert_eq!(select_named_action_index(&actions, "Click").unwrap(), 1);
3780    }
3781
3782    #[test]
3783    fn select_action_index_defaults_to_secondary_when_available() {
3784        let actions = vec![
3785            atspi::Action {
3786                name: "click".to_string(),
3787                description: String::new(),
3788                keybinding: String::new(),
3789            },
3790            atspi::Action {
3791                name: "show-menu".to_string(),
3792                description: String::new(),
3793                keybinding: String::new(),
3794            },
3795        ];
3796
3797        assert_eq!(select_action_index(&actions, None).unwrap(), 1);
3798    }
3799
3800    #[test]
3801    fn state_labels_serialize_in_bit_order() {
3802        let labels = state_labels(StateSet::new(atspi::State::Focused | atspi::State::Checked));
3803
3804        assert_eq!(labels, vec!["checked".to_string(), "focused".to_string()]);
3805    }
3806
3807    #[test]
3808    fn default_snapshot_limits_cover_deep_gtk4_trees() {
3809        // Nautilus 50 places file-list cells below depth 20 and can expose
3810        // more than 850 raw nodes. Keep the defaults above that known shape.
3811        assert_eq!(snapshot_limits(None, None), (1_000, 32));
3812    }
3813
3814    #[test]
3815    fn app_name_needle_ignores_blank_values_and_normalizes_the_rest() {
3816        assert_eq!(app_name_needle(None), None);
3817        assert_eq!(app_name_needle(Some("")), None);
3818        assert_eq!(app_name_needle(Some("   ")), None);
3819        assert_eq!(
3820            app_name_needle(Some("Calculator")).as_deref(),
3821            Some("calculator")
3822        );
3823        assert_eq!(
3824            app_name_needle(Some(" :1.64/org/a11y/atspi/accessible/root ")).as_deref(),
3825            Some(":1.64/org/a11y/atspi/accessible/root")
3826        );
3827    }
3828
3829    #[test]
3830    fn requested_snapshot_limits_remain_bounded() {
3831        assert_eq!(snapshot_limits(Some(0), Some(0)), (1, 0));
3832        assert_eq!(snapshot_limits(Some(100_000), Some(128)), (10_000, 64));
3833    }
3834
3835    #[test]
3836    fn app_discovery_budget_is_independent_of_requested_tree_size() {
3837        assert_eq!(snapshot_child_read_budgets(1), (256, 2_048, 1));
3838    }
3839
3840    #[test]
3841    fn traversal_attempts_and_queue_share_one_work_budget() {
3842        let mut traversal = BoundedTraversal::new(4);
3843        traversal.enqueue([1]);
3844
3845        assert_eq!(traversal.pop(), Some(1));
3846        traversal.enqueue(2..=10_000);
3847        assert_eq!(traversal.queue, VecDeque::from([2, 3, 4]));
3848
3849        assert_eq!(traversal.pop(), Some(2));
3850        traversal.enqueue(5..=10_000);
3851        assert_eq!(traversal.queue, VecDeque::from([3, 4]));
3852        assert_eq!(traversal.pop(), Some(3));
3853        assert_eq!(traversal.pop(), Some(4));
3854        assert_eq!(traversal.pop(), None);
3855        assert_eq!(traversal.attempted, 4);
3856        assert!(
3857            traversal.truncated(),
3858            "dropped enqueue items must be reported"
3859        );
3860    }
3861
3862    #[test]
3863    fn traversal_that_drains_within_budget_is_not_truncated() {
3864        let mut traversal = BoundedTraversal::new(3);
3865        traversal.enqueue([1, 2, 3]);
3866        assert_eq!(traversal.pop(), Some(1));
3867        assert_eq!(traversal.pop(), Some(2));
3868        assert_eq!(traversal.pop(), Some(3));
3869        assert_eq!(traversal.pop(), None);
3870        assert!(
3871            !traversal.truncated(),
3872            "exactly max_items real nodes is complete"
3873        );
3874    }
3875
3876    #[test]
3877    fn enqueue_at_zero_capacity_marks_the_traversal_truncated() {
3878        let mut traversal = BoundedTraversal::new(2);
3879        traversal.enqueue([1, 2]);
3880        assert_eq!(traversal.pop(), Some(1));
3881        assert_eq!(traversal.pop(), Some(2));
3882        assert!(!traversal.truncated(), "nothing dropped yet");
3883        // Capacity is zero; the offered item is dropped, which is the only
3884        // path that can mark truncation.
3885        traversal.enqueue([3]);
3886        assert!(traversal.queue.is_empty());
3887        assert_eq!(traversal.pop(), None);
3888        assert!(traversal.truncated());
3889    }
3890
3891    #[test]
3892    fn child_count_is_clamped_before_indexed_reads() {
3893        assert_eq!(bounded_child_count(-1, 4), 0);
3894        assert_eq!(bounded_child_count(3, 4), 3);
3895        assert_eq!(bounded_child_count(i32::MAX, 4), 4);
3896    }
3897
3898    #[tokio::test]
3899    async fn indexed_child_reads_consume_attempts_even_when_one_fails() {
3900        let calls = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
3901        let mut remaining_attempts = 3;
3902        let batch = fetch_indexed_up_to(100, 10, &mut remaining_attempts, {
3903            let calls = calls.clone();
3904            move |index| {
3905                let calls = calls.clone();
3906                async move {
3907                    calls.lock().unwrap().push(index);
3908                    if index == 1 {
3909                        Err(())
3910                    } else {
3911                        Ok(index)
3912                    }
3913                }
3914            }
3915        })
3916        .await;
3917
3918        assert_eq!(batch.items, vec![0, 2]);
3919        assert_eq!(batch.attempted, 3);
3920        assert!(
3921            batch.incomplete,
3922            "100 reported children, 3 attempted: budget cut must be reported"
3923        );
3924        assert!(!batch.all_failed());
3925        assert_eq!(*calls.lock().unwrap(), vec![0, 1, 2]);
3926        assert_eq!(remaining_attempts, 0);
3927
3928        let no_children = fetch_indexed_up_to(100, 10, &mut remaining_attempts, |_| async {
3929            Ok::<_, ()>(99)
3930        })
3931        .await;
3932        assert!(no_children.items.is_empty());
3933        assert_eq!(no_children.attempted, 0);
3934        assert!(!no_children.all_failed());
3935
3936        let mut failed_attempts = 2;
3937        let all_failed =
3938            fetch_indexed_up_to(2, 2, &mut failed_attempts, |_| async { Err::<i32, _>(()) }).await;
3939        assert!(all_failed.all_failed());
3940    }
3941
3942    fn document() -> FocusedElementSummary {
3943        FocusedElementSummary {
3944            role: "document web".into(),
3945            name: Some("Synthetic editor host".into()),
3946            editable: false,
3947            states: vec!["focused".into()],
3948            is_terminal: false,
3949        }
3950    }
3951
3952    #[test]
3953    fn focused_document_does_not_end_the_search_before_contenteditable() {
3954        assert!(focus_is_container(&document()));
3955        let mut entry = document();
3956        entry.role = "entry".into();
3957        entry.states.push("editable".into());
3958        // Chromium need not implement EditableText for keyboard input.
3959        assert!(!entry.editable);
3960        assert!(!focus_is_container(&entry));
3961    }
3962
3963    #[test]
3964    fn incomplete_descendants_do_not_make_the_document_a_definitive_recipient() {
3965        assert!(matches!(
3966            finish_focus_probe(true, false, Some(document())),
3967            FocusProbe::Incomplete
3968        ));
3969        assert!(matches!(
3970            finish_focus_probe(false, false, Some(document())),
3971            FocusProbe::Found(_)
3972        ));
3973    }
3974
3975    #[test]
3976    fn opt_in_snapshot_budget_reaches_controls_after_embedded_browser_content() {
3977        let (limit, _) = snapshot_limits(Some(4_000), None);
3978        assert_eq!(limit, 4_000);
3979        let mut traversal = BoundedTraversal::new(limit);
3980        traversal.enqueue(0..3_000);
3981        let mut reached_editor = false;
3982        while let Some(node) = traversal.pop() {
3983            reached_editor |= node == 2_500;
3984        }
3985        assert!(reached_editor);
3986        assert!(!traversal.truncated());
3987        let (default, _) = snapshot_limits(None, None);
3988        assert_eq!(default, 1_000);
3989    }
3990
3991    #[test]
3992    fn narrowing_keeps_the_spent_budget_and_forgets_dropped_work() {
3993        let mut traversal = BoundedTraversal::new(4);
3994        traversal.enqueue(0..6);
3995        assert!(traversal.truncated());
3996        assert_eq!(traversal.pop(), Some(0));
3997        traversal.narrow();
3998        assert!(
3999            !traversal.truncated(),
4000            "work dropped outside the subtree no longer counts"
4001        );
4002        assert_eq!(traversal.pop(), None);
4003        traversal.enqueue([10, 11, 12, 13]);
4004        assert_eq!(traversal.pop(), Some(10));
4005        assert_eq!(traversal.pop(), Some(11));
4006        assert_eq!(traversal.pop(), Some(12));
4007        assert_eq!(
4008            traversal.pop(),
4009            None,
4010            "the budget spent before narrowing still counts"
4011        );
4012        assert!(traversal.truncated());
4013    }
4014
4015    #[tokio::test]
4016    async fn text_snapshot_reads_selections_through_get_n_selections() {
4017        let running = start_field_fixture(FieldFixture {
4018            contents: "/tmp/old",
4019            caret: 8,
4020            selection: Some((5, 8)),
4021            ..Default::default()
4022        })
4023        .await;
4024        let proxy = open_accessible(&running.conn, &running.fields[0].0)
4025            .await
4026            .unwrap();
4027        let proxies = proxy.proxies().await.unwrap();
4028        let text = text_from_proxies(Some(&proxies)).await.unwrap();
4029        assert_eq!(text.content.as_deref(), Some("/tmp/old"));
4030        assert_eq!(text.selections.len(), 1);
4031        assert_eq!(
4032            (
4033                text.selections[0].start_offset,
4034                text.selections[0].end_offset
4035            ),
4036            (5, 8)
4037        );
4038    }
4039
4040    fn verified(replaced_selection: bool) -> FocusedTextInsert {
4041        FocusedTextInsert::Verified {
4042            role: "text".to_string(),
4043            replaced_selection,
4044            caret_after_text: true,
4045        }
4046    }
4047
4048    #[tokio::test]
4049    async fn focused_field_insert_lands_at_the_caret_and_reads_back() {
4050        let (outcome, state) = insert_into_fixture(
4051            FieldFixture {
4052                contents: "/home/",
4053                caret: 6,
4054                ..Default::default()
4055            },
4056            "x/doc",
4057        )
4058        .await;
4059        assert_eq!(outcome.unwrap(), verified(false));
4060        assert_eq!(state.contents, "/home/x/doc");
4061        assert_eq!(state.calls, ["insert", "caret"]);
4062        assert_eq!(state.caret, 11, "the caret ends after the text");
4063
4064        let (outcome, state) = insert_into_fixture(
4065            FieldFixture {
4066                contents: "ab",
4067                caret: 1,
4068                ..Default::default()
4069            },
4070            "שלום",
4071        )
4072        .await;
4073        assert_eq!(outcome.unwrap(), verified(false));
4074        assert_eq!(state.contents, "aשלוםb");
4075        assert_eq!(state.caret, 5);
4076        assert_eq!(state.calls, ["insert", "caret"]);
4077
4078        // A partial edit never rewrites the field, so embedded objects stay.
4079        let (outcome, state) = insert_into_fixture(
4080            FieldFixture {
4081                contents: "\u{fffc}\u{fffc}",
4082                caret: 1,
4083                ..Default::default()
4084            },
4085            "שלום",
4086        )
4087        .await;
4088        assert_eq!(outcome.unwrap(), verified(false));
4089        assert_eq!(state.contents, "\u{fffc}שלום\u{fffc}");
4090        assert_eq!(state.calls, ["insert", "caret"]);
4091    }
4092
4093    #[tokio::test]
4094    async fn focused_field_insert_is_exact_under_qt_length_rules() {
4095        for (text, selection, expected) in [
4096            ("x/doc", None, "/home/x/doc"),
4097            ("שלום", None, "/home/שלום"),
4098            ("שלום", Some((1, 5)), "/שלום/"),
4099        ] {
4100            let (outcome, state) = insert_into_fixture(
4101                FieldFixture {
4102                    contents: "/home/",
4103                    caret: 6,
4104                    selection,
4105                    edit: FieldEdit::QtLength,
4106                    toolkit: Some("Qt"),
4107                    ..Default::default()
4108                },
4109                text,
4110            )
4111            .await;
4112            assert_eq!(outcome.unwrap(), verified(selection.is_some()), "{text}");
4113            assert_eq!(state.contents, expected);
4114        }
4115    }
4116
4117    #[tokio::test]
4118    async fn focused_field_insert_needs_the_toolkit_for_non_ascii_text() {
4119        let (outcome, state) = insert_into_fixture(
4120            FieldFixture {
4121                contents: "/home/",
4122                caret: 6,
4123                toolkit: None,
4124                ..Default::default()
4125            },
4126            "שלום",
4127        )
4128        .await;
4129        assert!(
4130            matches!(&outcome, Ok(FocusedTextInsert::NotEditable(reason)) if reason.contains("toolkit")),
4131            "{outcome:?}"
4132        );
4133        assert_eq!(state.contents, "/home/");
4134        assert!(state.calls.is_empty(), "{:?}", state.calls);
4135
4136        // ASCII text has one length in every unit.
4137        let (outcome, state) = insert_into_fixture(
4138            FieldFixture {
4139                contents: "/home/",
4140                caret: 6,
4141                toolkit: None,
4142                ..Default::default()
4143            },
4144            "x",
4145        )
4146        .await;
4147        assert_eq!(outcome.unwrap(), verified(false));
4148        assert_eq!(state.contents, "/home/x");
4149    }
4150
4151    #[tokio::test]
4152    async fn focused_field_insert_replaces_the_selection() {
4153        let (outcome, state) = insert_into_fixture(
4154            FieldFixture {
4155                contents: "/tmp/old/x",
4156                caret: 8,
4157                selection: Some((8, 5)),
4158                ..Default::default()
4159            },
4160            "new",
4161        )
4162        .await;
4163        assert_eq!(outcome.unwrap(), verified(true));
4164        assert_eq!(state.contents, "/tmp/new/x");
4165        assert_eq!(state.calls, ["delete", "insert", "caret"]);
4166
4167        // An empty or fully selected field gets its contents set, as set_value does.
4168        for (contents, selection) in [("", None), ("/old/path", Some((0, 9)))] {
4169            let (outcome, state) = insert_into_fixture(
4170                FieldFixture {
4171                    contents,
4172                    caret: contents.chars().count() as i32,
4173                    selection,
4174                    ..Default::default()
4175                },
4176                "/home/x",
4177            )
4178            .await;
4179            assert_eq!(outcome.unwrap(), verified(selection.is_some()));
4180            assert_eq!(state.contents, "/home/x");
4181            assert_eq!(state.calls, ["set", "caret"]);
4182            assert_eq!(state.caret, 7);
4183        }
4184    }
4185
4186    #[tokio::test]
4187    async fn focused_field_insert_needs_a_focused_editable_field() {
4188        let unfocused = StateSet::new(atspi::State::Editable | atspi::State::Showing);
4189        let read_only = StateSet::new(atspi::State::Focused | atspi::State::Showing);
4190        for states in [unfocused, read_only] {
4191            let (outcome, state) = insert_into_fixture(
4192                FieldFixture {
4193                    contents: "keep",
4194                    caret: 4,
4195                    states,
4196                    ..Default::default()
4197                },
4198                "x",
4199            )
4200            .await;
4201            assert!(
4202                matches!(outcome.unwrap(), FocusedTextInsert::NotEditable(_)),
4203                "{states:?}"
4204            );
4205            assert_eq!(state.contents, "keep");
4206            assert!(state.calls.is_empty(), "{:?}", state.calls);
4207        }
4208    }
4209
4210    fn entry(contents: &'static str, focused: bool) -> FieldFixture {
4211        let mut states = StateSet::new(atspi::State::Editable | atspi::State::Showing);
4212        if focused {
4213            states.insert(atspi::State::Focused);
4214        }
4215        FieldFixture {
4216            contents,
4217            caret: contents.chars().count() as i32,
4218            states,
4219            ..Default::default()
4220        }
4221    }
4222
4223    /// Chromium puts every window under one app root, and AT-SPI focus can
4224    /// lag behind the compositor: a field still marked focused in another
4225    /// window is not the target.
4226    #[tokio::test]
4227    async fn focused_field_insert_stays_in_the_target_window() {
4228        let stale_and_target = |target_focused, target_active| {
4229            vec![
4230                FixtureWindow {
4231                    name: "Inbox",
4232                    active: false,
4233                    field: entry("stale", true),
4234                },
4235                FixtureWindow {
4236                    name: "Compose",
4237                    active: target_active,
4238                    field: entry("to: ", target_focused),
4239                },
4240            ]
4241        };
4242        let running = start_windows_fixture(stale_and_target(true, true)).await;
4243        let outcome =
4244            insert_text_at_focus_on(&running.conn, std::process::id(), Some("Compose"), "x").await;
4245        assert_eq!(outcome.unwrap(), verified(false));
4246        assert_eq!(running.take_state(0).contents, "stale");
4247        assert_eq!(running.take_state(1).contents, "to: x");
4248
4249        for (target_focused, target_active, title, why) in [
4250            (false, true, Some("Compose"), "has keyboard focus"),
4251            (true, false, Some("Compose"), "not active"),
4252            (true, true, Some("Drafts"), "could not be matched"),
4253            (true, true, None, "could not be matched"),
4254        ] {
4255            let running =
4256                start_windows_fixture(stale_and_target(target_focused, target_active)).await;
4257            let outcome =
4258                insert_text_at_focus_on(&running.conn, std::process::id(), title, "x").await;
4259            assert!(
4260                matches!(&outcome, Ok(FocusedTextInsert::NotEditable(reason)) if reason.contains(why)),
4261                "{title:?} focused={target_focused} active={target_active}: {outcome:?}"
4262            );
4263            for index in 0..2 {
4264                let state = running.take_state(index);
4265                assert!(state.calls.is_empty(), "{:?}", state.calls);
4266            }
4267        }
4268    }
4269
4270    #[tokio::test]
4271    async fn focused_field_insert_checks_the_untouched_text() {
4272        // Inserting "y" at 1 gives "xyyx"; appending gives "xyxy", which has
4273        // "y" at 1 and the right length too.
4274        let (outcome, state) = insert_into_fixture(
4275            FieldFixture {
4276                contents: "xyx",
4277                caret: 1,
4278                edit: FieldEdit::AppendAtEnd,
4279                ..Default::default()
4280            },
4281            "y",
4282        )
4283        .await;
4284        assert!(
4285            matches!(outcome, Ok(FocusedTextInsert::Mismatch { .. })),
4286            "{outcome:?}"
4287        );
4288        assert_eq!(state.contents, "xyxy");
4289    }
4290
4291    #[tokio::test]
4292    async fn focused_field_insert_bounds_each_edit_call() {
4293        let (outcome, state) = timeout(
4294            ACTION_QUERY_TIMEOUT + Duration::from_secs(3),
4295            insert_into_fixture(
4296                FieldFixture {
4297                    contents: "/home/",
4298                    caret: 6,
4299                    edit: FieldEdit::StallInsert,
4300                    ..Default::default()
4301                },
4302                "x",
4303            ),
4304        )
4305        .await
4306        .expect("a stalled InsertText must not hold the call");
4307        assert!(
4308            matches!(
4309                &outcome,
4310                Ok(FocusedTextInsert::EditFailed { reason, may_have_changed: true })
4311                    if reason.contains("did not answer")
4312            ),
4313            "{outcome:?}"
4314        );
4315        assert_eq!(state.contents, "/home/");
4316    }
4317
4318    #[tokio::test]
4319    async fn focused_field_insert_skips_password_fields() {
4320        let (outcome, state) = insert_into_fixture(
4321            FieldFixture {
4322                role: atspi::Role::PasswordText,
4323                role_name: "password text",
4324                ..Default::default()
4325            },
4326            "hunter2",
4327        )
4328        .await;
4329        assert_eq!(outcome.unwrap(), FocusedTextInsert::PasswordField);
4330        assert_eq!(state.contents, "");
4331        assert!(state.calls.is_empty(), "{:?}", state.calls);
4332    }
4333
4334    #[tokio::test]
4335    async fn focused_field_insert_reports_a_readback_mismatch() {
4336        let (outcome, state) = insert_into_fixture(
4337            FieldFixture {
4338                contents: "/home/",
4339                caret: 6,
4340                edit: FieldEdit::DropLastChar,
4341                ..Default::default()
4342            },
4343            "xyz",
4344        )
4345        .await;
4346        assert_eq!(
4347            outcome.unwrap(),
4348            FocusedTextInsert::Mismatch {
4349                expected_count: 9,
4350                read_count: 8,
4351                read_text: "xy".to_string(),
4352                read_truncated: false,
4353            }
4354        );
4355        assert_eq!(state.contents, "/home/xy");
4356        assert!(!state.calls.contains(&"caret"), "{:?}", state.calls);
4357    }
4358}
4359
4360/// Private-bus AT-SPI fixture for the type_text insert route: a registry, one
4361/// app owned by this process, its windows, and one text field in each.
4362#[cfg(test)]
4363pub(crate) mod insert_fixture {
4364    use super::*;
4365    use crate::test_sockets::PrivateBus;
4366    use std::sync::{Arc, Mutex};
4367
4368    const FOCUS_ROOT_PATH: &str = "/org/a11y/atspi/accessible/root";
4369
4370    #[derive(Default)]
4371    pub(crate) struct FieldState {
4372        pub(crate) contents: String,
4373        pub(crate) caret: i32,
4374        pub(crate) selection: Option<(i32, i32)>,
4375        pub(crate) calls: Vec<&'static str>,
4376    }
4377
4378    #[derive(Clone, Copy, PartialEq)]
4379    pub(crate) enum FieldEdit {
4380        Apply,
4381        /// Qt's bridge: InsertText resizes the text to `length` UTF-16 code
4382        /// units, padding with NUL.
4383        QtLength,
4384        /// The app keeps all but the last inserted character.
4385        DropLastChar,
4386        /// The app appends inserted text at the end, ignoring the position.
4387        AppendAtEnd,
4388        /// InsertText never answers.
4389        StallInsert,
4390    }
4391
4392    struct FocusNode {
4393        name: &'static str,
4394        role: atspi::Role,
4395        role_name: &'static str,
4396        states: StateSet,
4397        children: Vec<(String, OwnedObjectPath)>,
4398        text_field: bool,
4399    }
4400
4401    #[zbus::interface(name = "org.a11y.atspi.Accessible")]
4402    impl FocusNode {
4403        #[zbus(property)]
4404        fn child_count(&self) -> i32 {
4405            self.children.len() as i32
4406        }
4407
4408        #[zbus(property)]
4409        fn name(&self) -> &str {
4410            self.name
4411        }
4412
4413        fn get_role(&self) -> atspi::Role {
4414            self.role
4415        }
4416
4417        fn get_role_name(&self) -> &str {
4418            self.role_name
4419        }
4420
4421        fn get_state(&self) -> StateSet {
4422            self.states
4423        }
4424
4425        fn get_interfaces(&self) -> Vec<&str> {
4426            let mut interfaces = vec!["org.a11y.atspi.Accessible"];
4427            if self.text_field {
4428                interfaces.extend(["org.a11y.atspi.EditableText", "org.a11y.atspi.Text"]);
4429            }
4430            interfaces
4431        }
4432
4433        fn get_child_at_index(
4434            &self,
4435            index: i32,
4436        ) -> zbus::fdo::Result<((String, OwnedObjectPath),)> {
4437            self.children
4438                .get(index as usize)
4439                .cloned()
4440                .map(|child| (child,))
4441                .ok_or_else(|| zbus::fdo::Error::InvalidArgs("invalid child index".into()))
4442        }
4443    }
4444
4445    fn char_byte(contents: &str, offset: i32) -> zbus::fdo::Result<usize> {
4446        if offset < 0 {
4447            return Err(zbus::fdo::Error::InvalidArgs("invalid text offset".into()));
4448        }
4449        contents
4450            .char_indices()
4451            .map(|(byte_index, _)| byte_index)
4452            .chain(std::iter::once(contents.len()))
4453            .nth(offset as usize)
4454            .ok_or_else(|| zbus::fdo::Error::InvalidArgs("invalid text offset".into()))
4455    }
4456
4457    struct FieldText(Arc<Mutex<FieldState>>);
4458
4459    #[zbus::interface(name = "org.a11y.atspi.Text")]
4460    impl FieldText {
4461        #[zbus(property)]
4462        fn character_count(&self) -> i32 {
4463            self.0.lock().unwrap().contents.chars().count() as i32
4464        }
4465
4466        #[zbus(property)]
4467        fn caret_offset(&self) -> i32 {
4468            self.0.lock().unwrap().caret
4469        }
4470
4471        #[zbus(name = "GetNSelections")]
4472        fn get_n_selections(&self) -> i32 {
4473            i32::from(self.0.lock().unwrap().selection.is_some())
4474        }
4475
4476        fn get_selection(&self, index: i32) -> zbus::fdo::Result<(i32, i32)> {
4477            let state = self.0.lock().unwrap();
4478            state
4479                .selection
4480                .filter(|_| index == 0)
4481                .ok_or_else(|| zbus::fdo::Error::InvalidArgs("no such selection".into()))
4482        }
4483
4484        fn get_text(&self, start_offset: i32, end_offset: i32) -> zbus::fdo::Result<String> {
4485            let state = self.0.lock().unwrap();
4486            let start = char_byte(&state.contents, start_offset)?;
4487            let end = char_byte(&state.contents, end_offset)?;
4488            if end < start {
4489                return Err(zbus::fdo::Error::InvalidArgs("invalid text offsets".into()));
4490            }
4491            Ok(state.contents[start..end].to_string())
4492        }
4493
4494        fn set_caret_offset(&self, offset: i32) -> bool {
4495            let mut state = self.0.lock().unwrap();
4496            state.calls.push("caret");
4497            state.caret = offset;
4498            true
4499        }
4500    }
4501
4502    struct FixtureApplication(&'static str);
4503
4504    #[zbus::interface(name = "org.a11y.atspi.Application")]
4505    impl FixtureApplication {
4506        #[zbus(property)]
4507        fn toolkit_name(&self) -> &str {
4508            self.0
4509        }
4510    }
4511
4512    struct FieldEditable {
4513        state: Arc<Mutex<FieldState>>,
4514        edit: FieldEdit,
4515    }
4516
4517    impl FieldEditable {
4518        fn apply(&self, text: &str) -> String {
4519            let mut text = text.to_string();
4520            if self.edit == FieldEdit::DropLastChar {
4521                text.pop();
4522            }
4523            text
4524        }
4525    }
4526
4527    #[zbus::interface(name = "org.a11y.atspi.EditableText")]
4528    impl FieldEditable {
4529        async fn insert_text(
4530            &self,
4531            position: i32,
4532            text: &str,
4533            length: i32,
4534        ) -> zbus::fdo::Result<bool> {
4535            if self.edit == FieldEdit::StallInsert {
4536                std::future::pending::<()>().await;
4537            }
4538            let text = if self.edit == FieldEdit::QtLength {
4539                let mut units = text.encode_utf16().collect::<Vec<_>>();
4540                units.resize(length.max(0) as usize, 0);
4541                String::from_utf16_lossy(&units)
4542            } else {
4543                // Bytes, as the AT-SPI documentation and GTK count them.
4544                let take = (length.max(0) as usize).min(text.len());
4545                self.apply(text.get(..take).unwrap_or(text))
4546            };
4547            let mut state = self.state.lock().unwrap();
4548            state.calls.push("insert");
4549            let at = if self.edit == FieldEdit::AppendAtEnd {
4550                state.contents.len()
4551            } else {
4552                char_byte(&state.contents, position)?
4553            };
4554            state.contents.insert_str(at, &text);
4555            // Like a GTK entry, an insert does not move the caret.
4556            state.selection = None;
4557            Ok(true)
4558        }
4559
4560        fn delete_text(&self, start_pos: i32, end_pos: i32) -> zbus::fdo::Result<bool> {
4561            let mut state = self.state.lock().unwrap();
4562            state.calls.push("delete");
4563            let start = char_byte(&state.contents, start_pos)?;
4564            let end = char_byte(&state.contents, end_pos)?;
4565            state.contents.replace_range(start..end, "");
4566            state.caret = start_pos;
4567            state.selection = None;
4568            Ok(true)
4569        }
4570
4571        fn set_text_contents(&self, new_contents: &str) -> bool {
4572            let text = self.apply(new_contents);
4573            let mut state = self.state.lock().unwrap();
4574            state.calls.push("set");
4575            state.contents = text;
4576            state.caret = 0;
4577            state.selection = None;
4578            true
4579        }
4580    }
4581
4582    pub(crate) struct FieldFixture {
4583        pub(crate) role: atspi::Role,
4584        pub(crate) role_name: &'static str,
4585        pub(crate) states: StateSet,
4586        pub(crate) contents: &'static str,
4587        pub(crate) caret: i32,
4588        pub(crate) selection: Option<(i32, i32)>,
4589        pub(crate) edit: FieldEdit,
4590        /// The app root's ToolkitName; `None` serves no Application interface.
4591        /// The first window's field sets it.
4592        pub(crate) toolkit: Option<&'static str>,
4593    }
4594
4595    impl Default for FieldFixture {
4596        fn default() -> Self {
4597            Self {
4598                role: atspi::Role::Text,
4599                role_name: "text",
4600                states: StateSet::new(
4601                    atspi::State::Focused
4602                        | atspi::State::Focusable
4603                        | atspi::State::Editable
4604                        | atspi::State::Showing,
4605                ),
4606                contents: "",
4607                caret: 0,
4608                selection: None,
4609                edit: FieldEdit::Apply,
4610                toolkit: Some("GTK"),
4611            }
4612        }
4613    }
4614
4615    pub(crate) struct FixtureWindow {
4616        pub(crate) name: &'static str,
4617        pub(crate) active: bool,
4618        pub(crate) field: FieldFixture,
4619    }
4620
4621    pub(crate) struct RunningFields {
4622        // Dropped last: the bus outlives the peers.
4623        _peers: [zbus::Connection; 2],
4624        pub(crate) conn: AccessibilityConnection,
4625        pub(crate) fields: Vec<(ObjectRefOwned, Arc<Mutex<FieldState>>)>,
4626        _bus: PrivateBus,
4627    }
4628
4629    impl RunningFields {
4630        pub(crate) fn take_state(&self, index: usize) -> FieldState {
4631            std::mem::take(&mut *self.fields[index].1.lock().unwrap())
4632        }
4633    }
4634
4635    pub(crate) const FIXTURE_WINDOW: &str = "Files";
4636
4637    pub(crate) async fn start_windows_fixture(windows: Vec<FixtureWindow>) -> RunningFields {
4638        let bus = PrivateBus::start("cul-atspi-insert");
4639        let app = zbus::connection::Builder::address(bus.address())
4640            .unwrap()
4641            .build()
4642            .await
4643            .unwrap();
4644        let app_name = app.unique_name().unwrap().to_string();
4645        let toolkit = windows.first().and_then(|window| window.field.toolkit);
4646        let path = |kind: &str, index: usize| -> OwnedObjectPath {
4647            format!("/{kind}{index}").try_into().unwrap()
4648        };
4649        app.object_server()
4650            .at(
4651                FOCUS_ROOT_PATH,
4652                FocusNode {
4653                    name: "fixture-app",
4654                    role: atspi::Role::Application,
4655                    role_name: "application",
4656                    states: StateSet::empty(),
4657                    children: (0..windows.len())
4658                        .map(|index| (app_name.clone(), path("frame", index)))
4659                        .collect(),
4660                    text_field: false,
4661                },
4662            )
4663            .await
4664            .unwrap();
4665        if let Some(toolkit) = toolkit {
4666            app.object_server()
4667                .at(FOCUS_ROOT_PATH, FixtureApplication(toolkit))
4668                .await
4669                .unwrap();
4670        }
4671        let mut fields = Vec::new();
4672        for (index, window) in windows.into_iter().enumerate() {
4673            let mut frame_states = StateSet::new(atspi::State::Showing);
4674            if window.active {
4675                frame_states.insert(atspi::State::Active);
4676            }
4677            app.object_server()
4678                .at(
4679                    path("frame", index),
4680                    FocusNode {
4681                        name: window.name,
4682                        role: atspi::Role::Frame,
4683                        role_name: "frame",
4684                        states: frame_states,
4685                        children: vec![(app_name.clone(), path("field", index))],
4686                        text_field: false,
4687                    },
4688                )
4689                .await
4690                .unwrap();
4691            let fixture = window.field;
4692            let state = Arc::new(Mutex::new(FieldState {
4693                contents: fixture.contents.to_string(),
4694                caret: fixture.caret,
4695                selection: fixture.selection,
4696                calls: Vec::new(),
4697            }));
4698            let field_path = path("field", index);
4699            app.object_server()
4700                .at(
4701                    field_path.clone(),
4702                    FocusNode {
4703                        name: "Location",
4704                        role: fixture.role,
4705                        role_name: fixture.role_name,
4706                        states: fixture.states,
4707                        children: Vec::new(),
4708                        text_field: true,
4709                    },
4710                )
4711                .await
4712                .unwrap();
4713            app.object_server()
4714                .at(field_path.clone(), FieldText(Arc::clone(&state)))
4715                .await
4716                .unwrap();
4717            app.object_server()
4718                .at(
4719                    field_path.clone(),
4720                    FieldEditable {
4721                        state: Arc::clone(&state),
4722                        edit: fixture.edit,
4723                    },
4724                )
4725                .await
4726                .unwrap();
4727            let field = object_ref_from_id(&format!("{app_name}{}", field_path.as_str())).unwrap();
4728            fields.push((field, state));
4729        }
4730        let registry = zbus::connection::Builder::address(bus.address())
4731            .unwrap()
4732            .name("org.a11y.atspi.Registry")
4733            .unwrap()
4734            .serve_at(
4735                FOCUS_ROOT_PATH,
4736                FocusNode {
4737                    name: "main",
4738                    role: atspi::Role::DesktopFrame,
4739                    role_name: "desktop frame",
4740                    states: StateSet::empty(),
4741                    children: vec![(app_name, FOCUS_ROOT_PATH.try_into().unwrap())],
4742                    text_field: false,
4743                },
4744            )
4745            .unwrap()
4746            .build()
4747            .await
4748            .unwrap();
4749        let conn = AccessibilityConnection::from_address(bus.address().parse().unwrap())
4750            .await
4751            .unwrap();
4752        RunningFields {
4753            _peers: [app, registry],
4754            conn,
4755            fields,
4756            _bus: bus,
4757        }
4758    }
4759
4760    /// One active window, [`FIXTURE_WINDOW`], holding `field`.
4761    pub(crate) async fn start_field_fixture(field: FieldFixture) -> RunningFields {
4762        start_windows_fixture(vec![FixtureWindow {
4763            name: FIXTURE_WINDOW,
4764            active: true,
4765            field,
4766        }])
4767        .await
4768    }
4769
4770    /// Insert into a fresh one-window fixture. Returns the outcome and the
4771    /// field's state afterwards.
4772    pub(crate) async fn insert_into_fixture(
4773        field: FieldFixture,
4774        text: &str,
4775    ) -> (Result<FocusedTextInsert>, FieldState) {
4776        let running = start_field_fixture(field).await;
4777        let outcome = insert_text_at_focus_on(
4778            &running.conn,
4779            std::process::id(),
4780            Some(FIXTURE_WINDOW),
4781            text,
4782        )
4783        .await;
4784        (outcome, running.take_state(0))
4785    }
4786}