teksilo_core/widget_tree/

accessibility_emit_impl.rs

// SPDX-License-Identifier: MPL-2.0
// SPDX-FileCopyrightText: 2026 FernTech

//! AccessKit node emission: the walker that turns the widget arena into
//! `accesskit::Node` values — bounds, roles, properties, synthetic children,
//! and the subtree-merge helpers it leans on.

use super::*;

use super::accessibility_impl::to_accesskit_rect;
use crate::accessibility::{AccessNodeBuilder, to_accesskit_affine};

/// The node an adapter tells a reader holds focus: the focused node's
/// `active_descendant` when that names a node in the update, which is how
/// `accesskit_consumer` resolves it (`tree.rs:537-543`, `node.rs:966-971`).
fn focus_as_read(
    nodes: &[(accesskit::NodeId, accesskit::Node)],
    focus: accesskit::NodeId,
) -> accesskit::NodeId {
    nodes
        .iter()
        .find(|(id, _)| *id == focus)
        .and_then(|(_, node)| node.active_descendant())
        .filter(|descendant| nodes.iter().any(|(id, _)| id == descendant))
        .unwrap_or(focus)
}

impl WidgetTree {
    /// Walk the arena into a `TreeUpdate`.
    ///
    /// `speak` lets a message the framework's announcers hold ready enter the
    /// update, which it then does unless the update moves focus; the last
    /// element of the result says whether it did. A snapshot passes `false`
    /// and describes the tree the adapters have. See [`crate::announcer`].
    #[allow(clippy::type_complexity)]
    pub(super) fn build_accessibility_tree(
        &self,
        speak: bool,
    ) -> (
        accesskit::TreeUpdate,
        std::collections::HashMap<accesskit::NodeId, WidgetId>,
        std::collections::HashMap<accesskit::NodeId, teksilo_canvas::Rect>,
        super::accessibility_description_impl::DescriptionMemory,
        bool,
    ) {
        use crate::accessibility::{root_node_id, widget_id_to_node_id};

        let roots = self.arena.roots();
        let mut nodes: Vec<(accesskit::NodeId, accesskit::Node)> = Vec::new();
        let mut synthetic_parents: std::collections::HashMap<accesskit::NodeId, WidgetId> =
            std::collections::HashMap::new();
        // Global deduplication: AccessKit's consumer panics if the same child
        // NodeId appears in more than one node's children list across a TreeUpdate.
        // Track which widget first claimed each child so we can skip duplicates
        // and emit a diagnostic pointing at the two conflicting parents.
        let mut seen_children: std::collections::HashMap<accesskit::NodeId, WidgetId> =
            std::collections::HashMap::new();
        // Where each synthetic child sits inside its owner, for the ones
        // that declared local bounds. A pure translation re-places them
        // from here without walking again.
        let mut local_bounds: std::collections::HashMap<accesskit::NodeId, teksilo_canvas::Rect> =
            std::collections::HashMap::new();

        let mut root = accesskit::Node::new(accesskit::Role::Window);
        // Every rectangle below is logical; AccessKit wants physical. One
        // transform here converts the whole tree, synthetic children included.
        // See [`super::accessibility_impl::emit_root_transform`].
        super::accessibility_impl::emit_root_transform(&mut root, self.device_scale_factor());
        // Tag the root with the app's current locale (BCP-47, e.g. "fr-FR").
        // AccessKit nodes inherit `language` from their ancestors, so setting
        // it once on the Window node propagates to the whole tree. Without it,
        // VoiceOver/Narrator have no language hint and fall back to a default
        // (often English) TTS voice instead of the user's system voice. The
        // locale is fed in by the app layer via `WidgetTree::set_locale`.
        if let Some(locale) = self.locale_signal.get() {
            root.set_language(locale);
        }
        // The window's name. On AT-SPI the root is the window, and its label
        // is the only name `accesskit_atspi_common` gives the frame and sends
        // with `window:activate` (`adapter.rs:551-560`): without it Orca
        // announces every window as an unnamed "frame". Windows and macOS read
        // the title from the native window instead (`accesskit_windows`
        // `node.rs:1061-1068`; `accesskit_macos` `node.rs:316-321` drops a
        // root window's title on purpose), so this changes nothing there.
        if let Some(title) = self.window_title_for_accessibility() {
            root.set_label(title);
        }
        for &root_id in &roots {
            if self.arena.is_active(root_id) {
                let child_nid = widget_id_to_node_id(root_id);
                if seen_children.insert(child_nid, root_id).is_none() {
                    root.push_child(child_nid);
                } else {
                    eprintln!(
                        "Teksilo bug: duplicate accessibility child {:?} in Window root — \
                         already claimed by another parent. Please file a bug report.",
                        root_id
                    );
                }
            }
        }
        nodes.push((root_node_id(), root));

        // One pass, one set: a tooltip is placed once, on the first node that
        // may have it, and the walk order makes that the owner rather than the
        // anchor.
        let mut handled_tooltips: std::collections::HashSet<WidgetId> =
            std::collections::HashSet::new();
        let mut proxies = ProxyLedger::default();
        for &root_id in &roots {
            self.build_accessibility_recursive(
                root_id,
                teksilo_canvas::Transform2D::IDENTITY,
                &mut nodes,
                &mut synthetic_parents,
                &mut local_bounds,
                &mut seen_children,
                &mut handled_tooltips,
                &mut proxies,
            );
        }

        // A relation that names a composite names the proxy that stands for
        // it: the composite's own node is structure, and the presentational
        // pass below may drop it. Run before that pass, which keeps any node a
        // relation still names.
        proxies.redirect_relations(&mut nodes);

        // The focused node, resolved to something this walk actually emitted.
        //
        // Active is necessary and not sufficient. A widget can be alive and
        // still absent from the tree — inside an `access_exclude_subtree`, or
        // left out of an ancestor's `accessibility_children` (which is how
        // `SceneView` publishes fewer cards than it keeps warm). Naming it as
        // the focus is not a missing link but a broken update: the consumer
        // every platform adapter is built on resolves `focus` against the
        // nodes it was handed and rejects a tree where it cannot.
        //
        // So walk up to the nearest ancestor that did emit, which is the node
        // a screen reader would have put the user in anyway, and fall back to
        // the window root only if nothing on the chain emitted. The set costs
        // one pass over the nodes already built.
        let emitted: std::collections::HashSet<accesskit::NodeId> =
            nodes.iter().map(|(id, _)| *id).collect();
        let focus = self
            .focused
            .filter(|id| self.arena.is_active(*id))
            .and_then(|id| {
                let mut current = Some(id);
                while let Some(curr) = current {
                    let nid = widget_id_to_node_id(curr);
                    if emitted.contains(&nid) {
                        return Some(nid);
                    }
                    current = self.arena.parent(curr);
                }
                None
            })
            .unwrap_or_else(root_node_id);
        // A composite that hands its node to a proxy hands it the focus too.
        // An editor takes the keys on a wrapper whose node is structure and
        // keeps its text on a body the keyboard never lands on; a reader reads
        // the node named here when focus arrives, and `accesskit_atspi_common`
        // sends caret and selection events only for that node
        // (`adapter.rs:215-218`). Published on the wrapper, focus arrives on a
        // node with no name and no text, and no caret move is ever reported.
        let focus = Some(proxies.stand_in(focus))
            .filter(|nid| emitted.contains(nid))
            .unwrap_or(focus);

        // ── Name-from-content for row nodes ───────────────────────────
        // A virtualized row is two nodes: a thin structural wrapper
        // (`ListItemWrapper` / `TreeItemWrapper`) carrying the role, level
        // and selected/expanded state, and the app's delegate widget below
        // it carrying the visible label. ARIA computes an `option`'s /
        // `treeitem`'s name from its contents; AccessKit does not. Without
        // this pass the platform adapters announce a nameless "tree item",
        // and any client that matches a role AND a label — a screen-reader
        // search, the automation bridge's `find_node` — can never match a
        // row, because the two live on different nodes.
        //
        // Fill each nameless row node's name in from its first named
        // descendant, in the order they read. The descendant keeps its own
        // name (as in a browser's accessibility tree, where the text that
        // contributes to a computed name stays in the tree).
        {
            use accesskit::Role;
            use std::collections::HashMap;

            // Row roles that take their name from content. A row inside a
            // row (a `TreeView` nests each row under its parent row on
            // Windows and Linux) owns its own name: the search stops there
            // and does not descend, which is what keeps a parent row's name
            // its own content's rather than its first child row's.
            fn names_from_content(role: Role) -> bool {
                matches!(role, Role::TreeItem | Role::ListBoxOption)
            }

            let index: HashMap<accesskit::NodeId, usize> = nodes
                .iter()
                .enumerate()
                .map(|(i, (nid, _))| (*nid, i))
                .collect();

            let mut hoisted: Vec<(usize, String)> = Vec::new();
            for (i, (_, node)) in nodes.iter().enumerate() {
                if !names_from_content(node.role()) || node.label().is_some() {
                    continue;
                }
                // Depth-first, children in document order.
                let mut stack: Vec<accesskit::NodeId> =
                    node.children().iter().rev().copied().collect();
                while let Some(nid) = stack.pop() {
                    let Some(&j) = index.get(&nid) else { continue };
                    let descendant = &nodes[j].1;
                    if names_from_content(descendant.role()) {
                        continue;
                    }
                    match descendant.label() {
                        Some(label) if !label.trim().is_empty() => {
                            hoisted.push((i, label.to_string()));
                            break;
                        }
                        _ => stack.extend(descendant.children().iter().rev().copied()),
                    }
                }
            }
            for (i, label) in hoisted {
                nodes[i].1.set_label(label);
            }
        }

        // ── Presentational-node pruning ───────────────────────────────
        // Layout primitives (HStack/VStack/ZStack/Center/Padding/Expand/…)
        // emit empty `GenericContainer` / `Unknown` AT nodes purely to
        // carry visual structure. VoiceOver announces a `GenericContainer`
        // as "group", so a Button whose chrome is composed from these
        // primitives reads as "<label>, button, group". Browsers collapse
        // such semantically-empty nodes out of the platform tree
        // ("ignored" / "presentational" nodes); do the same — drop each
        // empty container and PROMOTE its children to its parent (bounds
        // are absolute, so promotion is structural only).
        //
        // A node is prunable only if it is a visible, content-free
        // `GenericContainer`/`Unknown`: no name, value, live region,
        // popup, relation, or focus/click action. The Window root, the
        // focused node, and any relationship target are always kept.
        {
            use std::collections::{HashMap, HashSet};

            // Nodes referenced by another node's relations must survive so
            // the reference can't dangle.
            let mut relation_targets: HashSet<accesskit::NodeId> = HashSet::new();
            for (_, node) in &nodes {
                relation_targets.extend(node.controls());
                relation_targets.extend(node.described_by());
                relation_targets.extend(node.labelled_by());
            }

            let prunable: HashSet<accesskit::NodeId> = nodes
                .iter()
                .filter(|(nid, node)| {
                    *nid != root_node_id()
                        && *nid != focus
                        && !relation_targets.contains(nid)
                        && is_presentational_container(node)
                })
                .map(|(nid, _)| *nid)
                .collect();

            if !prunable.is_empty() {
                // Pre-pruning children lists, for chain resolution.
                let children_map: HashMap<accesskit::NodeId, Vec<accesskit::NodeId>> = nodes
                    .iter()
                    .map(|(nid, node)| (*nid, node.children().to_vec()))
                    .collect();

                // A kept node's effective children: each prunable child is
                // replaced by its own (recursively resolved) kept children,
                // so chains of empty containers collapse in one pass. The
                // AT tree is acyclic, so the memo is the only guard needed.
                fn resolve(
                    nid: accesskit::NodeId,
                    children_map: &HashMap<accesskit::NodeId, Vec<accesskit::NodeId>>,
                    prunable: &HashSet<accesskit::NodeId>,
                    memo: &mut HashMap<accesskit::NodeId, Vec<accesskit::NodeId>>,
                ) -> Vec<accesskit::NodeId> {
                    if let Some(cached) = memo.get(&nid) {
                        return cached.clone();
                    }
                    let mut out = Vec::new();
                    if let Some(kids) = children_map.get(&nid) {
                        for &c in kids {
                            if prunable.contains(&c) {
                                out.extend(resolve(c, children_map, prunable, memo));
                            } else {
                                out.push(c);
                            }
                        }
                    }
                    memo.insert(nid, out.clone());
                    out
                }

                let mut memo: HashMap<accesskit::NodeId, Vec<accesskit::NodeId>> = HashMap::new();
                for (nid, node) in &mut nodes {
                    if prunable.contains(nid) {
                        continue;
                    }
                    let resolved = resolve(*nid, &children_map, &prunable, &mut memo);
                    if children_map.get(nid) != Some(&resolved) {
                        node.set_children(resolved);
                    }
                }
                nodes.retain(|(nid, _)| !prunable.contains(nid));
            }
        }

        // ── Strip dangling children ───────────────────────────────────
        // A node's children list may name a NodeId that never reached this
        // update. The walker's own pushes cannot do that (it pushes a child
        // only after `arena.is_active`), but `attach_scene_child_under` can:
        // it is called from a widget's `accessibility()` — which has no arena
        // — to graft a *sibling* widget's node under a synthetic parent, and
        // that widget may have gone dormant, in which case the walker emitted
        // nothing for it.
        //
        // A dangling child is not a lost link, it is a broken tree: the
        // consumer walks children to build the filtered tree every platform
        // adapter reads, and a child it cannot resolve is an unreachable
        // parent for everything below it. This is the structural twin of the
        // relation strip immediately below, and it is enforced HERE rather
        // than at each caller because a caller that could check would not
        // need to ask: `Widget::accessibility` sees no arena by design, and
        // a visibility gate written during layout settles after the widget
        // that wrote it has already been asked for its node.
        //
        // Runs before the relation strip so a child removed here cannot be
        // resurrected as a relation target by a later pass.
        //
        // Each emitted node's position in `nodes`, built once here and read by
        // the two strips and the cell naming pass below: none of them adds,
        // removes or reorders a node (the announcer nodes appended after the
        // strips are absent from it, and no strip or cell looks for them).
        let emitted: std::collections::HashMap<accesskit::NodeId, usize> = nodes
            .iter()
            .enumerate()
            .map(|(i, (id, _))| (*id, i))
            .collect();
        for (_, node) in &mut nodes {
            if node.children().iter().all(|c| emitted.contains_key(c)) {
                continue;
            }
            let kept: Vec<_> = node
                .children()
                .iter()
                .filter(|c| emitted.contains_key(*c))
                .copied()
                .collect();
            node.set_children(kept);
        }

        // Strip relationship targets (controls, described_by, labelled_by) that
        // reference NodeIds absent from the emitted tree. Dormant widgets (e.g.
        // inactive tab panels) are excluded from the TreeUpdate; if a node still
        // holds a `push_controlled` / `push_described_by` / `push_labelled_by`
        // reference to one of them, accesskit_macos will unwrap() it and panic
        // when VoiceOver follows the linked_ui_elements attribute.
        //
        // `labelled_by` is the one that costs a name rather than a link: the
        // consumer concatenates its targets' values to build the node's name
        // (`accesskit_consumer::node::write_label`), and a dangling target
        // panics the iterator before it gets there.
        for (_, node) in &mut nodes {
            let controlled: Vec<_> = node
                .controls()
                .iter()
                .filter(|id| emitted.contains_key(*id))
                .copied()
                .collect();
            if controlled.len() != node.controls().len() {
                node.set_controls(controlled);
            }
            let described: Vec<_> = node
                .described_by()
                .iter()
                .filter(|id| emitted.contains_key(*id))
                .copied()
                .collect();
            if described.len() != node.described_by().len() {
                node.set_described_by(described);
            }
            let labelled: Vec<_> = node
                .labelled_by()
                .iter()
                .filter(|id| emitted.contains_key(*id))
                .copied()
                .collect();
            if labelled.len() != node.labelled_by().len() {
                node.set_labelled_by(labelled);
            }
        }

        // The framework's own live regions, last in the root's child list so
        // they sit after the application's content in reading order: one node
        // for each message spoken in the last few seconds, each from an id the
        // tree has never used. See [`crate::announcer`] for why an
        // announcement is a node that was never in the tree rather than a
        // label edited in place or a node shown again.
        //
        // A message ready to enter does so only in an update that leaves
        // focus where the last one put it: the adapters raise an update's
        // announcements before its focus event, and a reader that stops to
        // read the new focus cuts the message. Focus is compared as the
        // consumer resolves it, so a list's new current row is a move.
        let ready = speak
            && (self.announcer_polite.entering().is_some()
                || self.announcer_assertive.entering().is_some());
        let moves_focus = ready
            && self.cached_a11y.as_ref().is_some_and(|last| {
                focus_as_read(&last.nodes, last.focus) != focus_as_read(&nodes, focus)
            });
        let admitted = ready && !moves_focus;
        // What waits is heard after the arrival, by every reader.
        let held: Vec<&str> = if moves_focus {
            [
                self.announcer_polite.entering(),
                self.announcer_assertive.entering(),
            ]
            .into_iter()
            .flatten()
            .collect()
        } else {
            Vec::new()
        };
        let announcer_nodes: Vec<(accesskit::NodeId, accesskit::Node)> = self
            .announcer_polite
            .nodes(admitted)
            .chain(self.announcer_assertive.nodes(admitted))
            .collect();
        if let Some((_, root)) = nodes.iter_mut().find(|(id, _)| *id == root_node_id()) {
            for (id, _) in &announcer_nodes {
                root.push_child(*id);
            }
        }
        nodes.extend(announcer_nodes);

        // A table cell is named after the text it shows, as ARIA names it
        // from its content and the consumer does not. Before the description
        // pass, which reads names; after the relation strip, so every target
        // it adds is present.
        super::accessibility_cell_name_impl::name_cells_from_content(&mut nodes, &emitted);

        // Last, on the nodes this update carries: a `described_by` relation
        // reaches no screen reader through AccessKit, so its targets' text is
        // written onto the node's `description`, which every adapter exposes.
        // After the relation strip, so every target named is present.
        let descriptions = self.describe_from_relations(&mut nodes, focus, &held);

        (
            accesskit::TreeUpdate {
                nodes,
                tree: Some(accesskit::TreeInfo::new(root_node_id())),
                tree_id: accesskit::TreeId::ROOT,
                focus,
            },
            synthetic_parents,
            local_bounds,
            descriptions,
            admitted,
        )
    }

    #[allow(clippy::too_many_arguments)]
    pub(super) fn build_accessibility_recursive(
        &self,
        id: WidgetId,
        // The transform carrying this node's bounds space into the space its
        // AccessKit parent is described in. Identity for all but the direct
        // children of a content-transform node; see the `set_transform` call
        // below for why it is emitted there and nowhere else.
        content_to_parent: teksilo_canvas::Transform2D,
        nodes: &mut Vec<(accesskit::NodeId, accesskit::Node)>,
        synthetic_parents: &mut std::collections::HashMap<accesskit::NodeId, WidgetId>,
        local_bounds: &mut std::collections::HashMap<accesskit::NodeId, teksilo_canvas::Rect>,
        seen_children: &mut std::collections::HashMap<accesskit::NodeId, WidgetId>,
        // Tooltips whose text has already been placed on a node this pass.
        // One tooltip describes one control, so once an owner has taken it the
        // anchor further down must not take it again -- a description announced
        // twice on the way into a control is worse than one announced in the
        // wrong place.
        handled_tooltips: &mut std::collections::HashSet<WidgetId>,
        // What composites above have handed down to the descendants that
        // stand for them (`Widget::accessibility_proxy`).
        proxies: &mut ProxyLedger,
    ) {
        use crate::accessibility::widget_id_to_node_id;
        use crate::widget_builder::AccessSubtreeMode;

        if !self.arena.is_active(id) {
            return;
        }

        let node = self
            .arena
            .get(id)
            .expect("widget id is not in the arena (destroyed?)");
        let mut builder = AccessNodeBuilder::for_widget(id);
        node.widget.accessibility(&mut builder);
        // Same call, same place, as `build_overridden_builder` — the two builder
        // paths are parallel by construction and a derivation added to one of them
        // only is a node that reads differently to a test than to a screen reader.
        self.announce_context_menu(id, &mut builder);
        self.announce_focusable(id, &mut builder);

        // Whatever the composites this node stands for handed down (see
        // `Widget::accessibility_proxy`). Taken out of the ledger here, so a
        // composite below that names a proxy of its own passes them on rather
        // than leaving a second copy behind.
        let standing_for = proxies.standing_for.remove(&id).unwrap_or_default();
        let mut reserved_tooltip = proxies.tooltips.remove(&id);
        let proxy = self.live_accessibility_proxy(id);

        // Apply builder-level overrides AFTER the inner widget has
        // emitted its defaults, so the overrides win for scalar fields
        // and append on relationship lists.
        //
        // A composite with a proxy keeps none of them. Its node is structure,
        // and what an application attached to it (the only id it can reach)
        // belongs on the node that holds focus: its overrides, those it was
        // handed from further up, and the tooltip it owns all move down to the
        // proxy, which applies them after its own so the application still
        // has the last word. The tooltip is marked handled now, because the
        // walk passes the composite's chrome, where the tooltip is anchored,
        // before it reaches the proxy.
        match proxy {
            Some(proxy_id) => {
                let mut chain = Vec::with_capacity(standing_for.len() + 1);
                chain.push(id);
                chain.extend(standing_for.iter().copied());
                // Two composites can name the same proxy: a `DateEdit` names
                // its `TextInput`'s field, and so does the `TextInput`. The
                // outer one was walked first and left its share already; it
                // goes after this one's, since the order is innermost first.
                if let Some(outer) = proxies.standing_for.remove(&proxy_id) {
                    chain.extend(outer);
                }
                proxies.standing_for.insert(proxy_id, chain);
                if let Some(content) = reserved_tooltip
                    .take()
                    .or_else(|| self.tooltip_claim_for_proxy(id, handled_tooltips))
                {
                    handled_tooltips.insert(content);
                    // An outer composite that names the same proxy reserved
                    // its tooltip first; keep it rather than overwrite it.
                    proxies.tooltips.entry(proxy_id).or_insert(content);
                }
                proxies
                    .nodes
                    .insert(widget_id_to_node_id(id), widget_id_to_node_id(proxy_id));
            }
            None => {
                // The menu a composite owns is offered where its node went:
                // focus arrives here now, and the dispatcher already finds the
                // composite's factory from here by walking up.
                for &composite in &standing_for {
                    self.announce_context_menu(composite, &mut builder);
                }
                // Before the overrides, so an application's own name still
                // wins over the row label that replaces a default here.
                self.yield_default_name(id, &standing_for, &mut builder);
                self.apply_access_overrides(id, &mut builder);
                for &composite in &standing_for {
                    self.apply_access_overrides(composite, &mut builder);
                }
            }
        }

        let subtree_mode = node.access_subtree;
        // G17: a widget may present a different child ORDER to assistive tech
        // than its paint / z-order child order — e.g. TableView / TreeTableView
        // build body rows before the header for correct z-stacking, but the
        // header must read first in the AT (and Tab) linear order. Honour the
        // widget's `accessibility_children()` override when it provides one;
        // otherwise use the arena's paint-order child list. Geometry and paint
        // are untouched (they keep reading `arena.children`).
        let at_children_owned;
        let children: &[WidgetId] = match node.widget.accessibility_children() {
            Some(v) => {
                at_children_owned = v;
                &at_children_owned
            }
            None => self.arena.children(id),
        };

        // Subtree dispatch:
        //   Inherit  — push child NodeIds onto the parent and recurse normally
        //   Exclude  — neither push nor recurse: descendants vanish from AT
        //   Merge    — collect descendants' label/description/value/actions
        //              into THIS node, then prune (no push, no recurse)
        // The children this node will recurse into: every active child it
        // pushed or a redirect claimed (a claimed child is still built, under
        // the node the claimer attaches it to), and never a duplicate. Since
        // `accessibility_children` may name any descendant, two parents can
        // claim one id; building it twice would emit its node twice.
        let mut to_recurse: Vec<WidgetId> = Vec::new();
        match subtree_mode {
            AccessSubtreeMode::Inherit => {
                for &child_id in children {
                    if self.arena.is_active(child_id) {
                        let child_nid = widget_id_to_node_id(child_id);
                        // Checked before the redirect, so a child claimed
                        // twice is reported and built once whichever way
                        // either claim came.
                        if let Some(&prior_parent) = seen_children.get(&child_nid) {
                            eprintln!(
                                "Teksilo bug: duplicate accessibility child {:?}: \
                                 first claimed by parent {:?}, now also claimed by {:?}. \
                                 Please file a bug report.",
                                child_id, prior_parent, id
                            );
                            continue;
                        }
                        // AT-redirect hook (scene logical-tree auto-graft):
                        // walk up the arena from `id` asking every
                        // opted-in ancestor whether it claims this
                        // descendant. First `Some(_)` wins, scanned
                        // bottom-up so closest ancestor takes
                        // priority. The immediate parent is queried
                        // first if it opts in, direct-child
                        // relocation being the special case of an
                        // ancestor walk of length zero.
                        //
                        // Performance: most widgets default
                        // `wants_descendant_redirects = false` and
                        // are skipped without calling the hook, so
                        // the walk is O(opted-in ancestors) per
                        // child push, typically 0 or 1 for a
                        // SceneView-rooted subtree.
                        seen_children.insert(child_nid, id);
                        to_recurse.push(child_id);
                        if self.ancestor_chain_redirects(id, child_id) {
                            continue;
                        }
                        builder.inner_mut().push_child(child_nid);
                    }
                }
            }
            AccessSubtreeMode::Exclude => {
                // No children pushed, no descendants recursed-into.
            }
            AccessSubtreeMode::Merge => {
                merge_descendants_into(&mut builder, id, &self.arena);
            }
        }

        let bounds = self.arena.bounds(id);
        builder.inner_mut().set_bounds(to_accesskit_rect(bounds));
        // …and, where those bounds are not already in window space, the
        // transform that puts them there.
        //
        // A **content** transform node — `SceneView` is the only one today —
        // declares that its children are laid out in a coordinate system of
        // its own: a card at scene (100, 100) has arena bounds of (100, 100)
        // whatever the camera is doing. Writing that rectangle out untouched
        // told assistive technology the card was at window (100, 100), which
        // is where it is only at pan zero: an explore-by-touch probe, a
        // braille routing key and a magnifier following focus all resolved
        // against a rectangle the card is not in.
        //
        // The fix is the mechanism AccessKit already has for exactly this.
        // `Node::transform` applies "to any coordinates within this node and
        // its descendants, including the `bounds` property of this node", and
        // `bounds` are read "in the coordinate space of the nearest ancestor
        // with a non-`None` transform". So the whole scene subtree needs ONE
        // declaration, on each child at the boundary: every rectangle below it
        // — a card, a label inside the card, a text run's per-character boxes
        // — stays in scene coordinates and is projected by the consumer, which
        // is also what makes `node_at_point` descend correctly (it feeds each
        // child `inv(child.direct_transform()) * point`).
        //
        // Emitted at the boundary and only there: a grandchild that re-emitted
        // it would compose it twice. And emitted for *content* transforms only
        // — a `Scale` or `Rotate` scope is a visual effect applied to a widget
        // whose bounds are already in window space, so its subtree's
        // coordinates are unchanged and a screen reader is not asked to chase
        // a 200 ms tween.
        if !content_to_parent.is_identity() {
            builder
                .inner_mut()
                .set_transform(to_accesskit_affine(content_to_parent));
        }

        // Framework-driven disabled gate. Respects an
        // `access_disabled(false)` override that wants to clear
        // arena-driven disabled state too — without this short-circuit,
        // `clear_disabled()` in the override layer would be re-set here.
        let force_clear_disabled =
            self.access_disabled_override(id, proxy.is_some(), &standing_for) == Some(false);
        if !self.arena.is_enabled(id) && !force_clear_disabled {
            builder.set_disabled();
        }

        // ── the tooltip's text, onto the node that will be read ───────────
        //
        // Not necessarily the node the overlay hangs off. A composing control
        // anchors the tooltip on an inner chrome node -- the thing with the
        // right bounds to open against -- and keeps its role, its name and its
        // focusability on its own outer node. Emitting on the anchor put the
        // description on an unnamed box beside the control: present in the
        // tree, attached to nothing anyone reads. Since a plain tooltip is
        // never auto-shown on focus (see `docs/tooltips.md`), that description
        // IS the whole non-pointer path for the tier, and it reached nobody.
        //
        // So a tooltip names an owner, and the owner is honoured here -- but
        // only where exactly ONE tooltip claims it. `BuildContext` records the
        // widget that was building, and one build can attach many tooltips: a
        // list body pane attaches one per visible row, all of them naming the
        // pane. Granting that would put one row's text on the pane and lose
        // every other row's entirely. A contested claim is no claim, and each
        // of those tooltips falls back to its own anchor, which is where they
        // already were.
        //
        // A composite that handed its node to a proxy handed its tooltip with
        // it, above; the proxy takes it here on the owner's terms (a node a
        // reader stops on, with no description of its own), or falls back to
        // the usual search.
        let tooltip = if proxy.is_some() {
            None
        } else {
            reserved_tooltip
                .filter(|_| {
                    !is_presentational_container(builder.inner_mut())
                        && builder.inner_mut().description().is_none()
                })
                .or_else(|| self.tooltip_description_target(id, handled_tooltips, &mut builder))
        };
        if let Some(content_id) = tooltip {
            if self
                .tooltips
                .iter()
                .any(|t| t.content_id == content_id && t.overlay_id.is_some())
            {
                // Shown: the content node is live in the AT tree, so the
                // richer `described_by` relation can point straight at it.
                // Its text still reaches a reader as this node's description,
                // which `describe_from_relations` writes from the relation at
                // the end of the build: no adapter reads the relation itself,
                // and showing the tooltip used to take away the only
                // description the control had.
                builder
                    .inner_mut()
                    .push_described_by(widget_id_to_node_id(self.tooltip_content_node(content_id)));
                handled_tooltips.insert(content_id);
            } else if let Some(text) = self.tooltip_access_description(content_id) {
                // Not shown. `described_by` cannot be used — the content is a
                // dormant node and absent from the AT tree — and a *plain*
                // tooltip is never auto-shown on focus, so gating the relation
                // on `overlay_id` left the whole tier (the majority of call
                // sites) with no screen-reader path at all. Copy the text onto
                // the control as a static description instead, which is what a
                // keyboard-only or screen-reader user actually reaches.
                builder.set_description(text);
                handled_tooltips.insert(content_id);
            }
        }

        // The fourth element — the widget-local rects of any synthetic
        // children — is what lets a pure translation re-place the runs
        // without a full walk. Recorded by `sync_accessibility`.
        let (node_id, ak_node, synthetic_children, synthetic_local_bounds) = builder.build(id);
        nodes.push((node_id, ak_node));
        local_bounds.extend(synthetic_local_bounds);
        // Merge the widget's emitted synthetic children into the
        // tree update and record their parent-widget mapping so
        // `handle_accessibility_actions` can route incoming
        // `ActionRequest`s targeting these child NodeIds back to
        // the owning widget.
        for (syn_id, syn_node) in synthetic_children {
            nodes.push((syn_id, syn_node));
            synthetic_parents.insert(syn_id, id);
        }

        // Recurse only for `Inherit` — `Exclude` and `Merge` prune
        // descendants from the AT tree.
        if matches!(subtree_mode, AccessSubtreeMode::Inherit) {
            // What space this node hands its children. A content transform is
            // the one kind that changes it; everything else — including a
            // `Scale` / `Rotate` self transform — leaves its children in the
            // space it was itself described in.
            let child_space = if node.content_transform {
                node.transform_prop
                    .as_ref()
                    .map(|p| p.get())
                    .unwrap_or(teksilo_canvas::Transform2D::IDENTITY)
            } else {
                teksilo_canvas::Transform2D::IDENTITY
            };
            for &child_id in &to_recurse {
                self.build_accessibility_recursive(
                    child_id,
                    child_space,
                    nodes,
                    synthetic_parents,
                    local_bounds,
                    seen_children,
                    handled_tooltips,
                    proxies,
                );
            }
        }
    }

    /// Walk the arena from `parent_id` up through ancestors, asking
    /// each opted-in widget whether it claims `descendant` via
    /// [`Widget::a11y_redirect_descendant`]. First widget that
    /// returns `Some(_)` wins (closest-ancestor-first scan). Returns
    /// `true` if any ancestor claimed the descendant — the caller
    /// then skips the default child-list push.
    ///
    /// Cost: bounded by arena depth, but most widgets default
    /// `wants_descendant_redirects = false` and short-circuit
    /// without invoking the redirect hook itself. Trees with no
    /// opted-in ancestors pay one `is_active` + one `Widget::
    /// wants_descendant_redirects` call per ancestor — both
    /// trivial — and walk to root.
    ///
    /// `parent_id` is queried *first* — direct-child relocation is
    /// just the special case of an ancestor walk of length one.
    fn ancestor_chain_redirects(&self, parent_id: WidgetId, descendant: WidgetId) -> bool {
        let mut current = Some(parent_id);
        while let Some(curr) = current {
            let Some(curr_node) = self.arena.get(curr) else {
                break;
            };
            if curr_node.widget.wants_descendant_redirects()
                && curr_node
                    .widget
                    .a11y_redirect_descendant(curr, descendant)
                    .is_some()
            {
                return true;
            }
            current = self.arena.parent(curr);
        }
        false
    }

    /// Which tooltip's text this node should carry, if any.
    ///
    /// Two ways a node can come to own a tooltip's description, tried in that
    /// order:
    ///
    ///   * **as the claimed owner** -- the widget that was building when the
    ///     tooltip was attached. This is the case the whole mechanism exists
    ///     for: `Button` and the two dozen controls shaped like it hang the
    ///     overlay off an inner chrome node while their role and name live
    ///     out here. Granted only when this node is *unambiguously* the
    ///     owner: exactly one tooltip may claim it, and the node must be
    ///     something an assistive technology would actually stop on rather
    ///     than an anonymous box.
    ///
    ///   * **as the anchor** -- the historic behaviour, and still correct for
    ///     a widget that anchors its tooltip on itself. Also the fallback for
    ///     everything the first case declines, so declining is always safe:
    ///     the worst it can do is leave the description exactly where it was
    ///     before any of this existed.
    ///
    /// The order matters and only works because of the walk's order. An
    /// anchor is always a descendant of the widget that built it, and parents
    /// are visited first, so an owner has already taken its tooltip (and said
    /// so in `handled`) by the time the anchor is reached. Reverse the walk
    /// and both would take it.
    fn tooltip_description_target(
        &self,
        id: WidgetId,
        handled: &std::collections::HashSet<WidgetId>,
        builder: &mut AccessNodeBuilder,
    ) -> Option<WidgetId> {
        let mut claims = self
            .tooltips
            .iter()
            .filter(|t| t.description_owner_id == id && !handled.contains(&t.content_id));
        // `next()` twice rather than `count()`: one claim is the answer, two is
        // a refusal, and there is nothing to learn from a third.
        if let (Some(only), None) = (claims.next(), claims.next())
            && only.anchor_id != id
            // An anonymous container is not a place a description can be read
            // from, and a widget whose own `accessibility()` leaves it one
            // (`TextInput` says so out loud, keeping the real role on an inner
            // field) is not the control being described either. Nothing is
            // lost by declining: the anchor still takes it below.
            && !is_presentational_container(builder.inner_mut())
            // A description the widget wrote itself is the widget's own words
            // about itself; a tooltip's is supplementary. Both land in the one
            // scalar field, so the specific one wins. `MenuItem::trailing_hint`
            // is the case that made this reachable.
            && builder.inner_mut().description().is_none()
        {
            return Some(only.content_id);
        }
        self.tooltips
            .iter()
            .find(|t| t.anchor_id == id && !handled.contains(&t.content_id))
            .map(|t| t.content_id)
    }

    /// Announce the context menu a widget owns, before any override runs.
    ///
    /// The dispatcher has always *serviced* `Action::ShowContextMenu` by falling
    /// through to the node's `.context_menu(..)` factory, so an assistive
    /// technology that tried the action got a menu. Nothing ever told it the
    /// action was there, and an AT offers what a node advertises: the menu was
    /// reachable and undiscoverable at the same time.
    ///
    /// That is not a cosmetic gap wherever a menu is the accessible route to
    /// something else. A row that puts its actions on hover buttons has to hide
    /// those buttons from the AT -- a control that exists only under a pointer
    /// does not exist for a keyboard -- and offer the same actions on its context
    /// menu instead. Unannounced, that leaves the actions with no route at all.
    ///
    /// Only where the node owns the factory ITSELF, not wherever the ancestor walk
    /// would eventually find one: every descendant of a widget with a menu would
    /// otherwise advertise it, and an AT would offer the same menu on a dozen
    /// nested boxes. Applied BEFORE the overrides so `access_remove_action` still
    /// takes it away, and so a widget wiring its own `on_access_action` handler is
    /// not given a second one.
    /// Announce that a focusable node can be focused, before any override runs.
    ///
    /// The sibling of [`Self::announce_context_menu`], for the same reason. The
    /// dispatcher has always *serviced* `Action::Focus` for any node -- the
    /// `AccessAction` arm calls `focus_with_origin_ops` itself rather than
    /// handing the action to the widget -- so an assistive technology that tried
    /// it got focus. Nothing told it the action was there, and an AT offers what
    /// a node advertises: focus was reachable and undiscoverable at the same
    /// time.
    ///
    /// Leaving it to each widget made it a rule that had to be remembered ~40
    /// times and was not: every stock button remembered, while `ListView`,
    /// `TreeView`, `TableView`, `TreeTableView`, `GridView`, `MenuList` and
    /// `OverlayTrigger` did not -- so a screen reader could not put focus in a
    /// list, a tree, a table, a grid or an open menu. Deriving it from the
    /// arena's own focusable flag makes the advertisement true by construction
    /// and keeps it true for widgets not yet written.
    ///
    /// Gated on the *arena* flag rather than on the widget's opinion, because
    /// that flag is what `focus_with_origin_ops` will actually honour -- a node
    /// that is not focusable would advertise an action that then declines to
    /// land. Applied BEFORE the overrides, so `access_remove_action` can still
    /// take it away.
    fn announce_focusable(&self, id: WidgetId, builder: &mut AccessNodeBuilder) {
        if self
            .arena
            .get(id)
            .is_some_and(|node| self.is_node_focusable(node))
            && !builder.actions().contains(&accesskit::Action::Focus)
        {
            builder.add_action(accesskit::Action::Focus);
        }
    }

    fn announce_context_menu(&self, id: WidgetId, builder: &mut AccessNodeBuilder) {
        let offers = |id: WidgetId| {
            self.arena.get(id).is_some_and(|node| {
                node.context_menu_factory.is_some() || node.context_menu_contribution.is_some()
            })
        };
        // A data view's own node offers the menu its current row would open
        // (the row, or the delegate or cell inside it, carries it).
        let reaches_one = || {
            let mut current = Some(self.resolve_context_menu_target(id));
            while let Some(at) = current {
                if offers(at) {
                    return true;
                }
                if at == id {
                    break;
                }
                current = self.arena.get(at).and_then(|node| node.parent);
            }
            false
        };
        if (offers(id) || reaches_one())
            && !builder
                .actions()
                .contains(&accesskit::Action::ShowContextMenu)
        {
            builder.add_action(accesskit::Action::ShowContextMenu);
        }
    }

    /// Whether the node `id` publishes to assistive technology offers
    /// `Action::Focus`.
    ///
    /// Answered off the same builder the AT tree is emitted from — widget
    /// emission, then `announce_focusable`, then the app's overrides (which can
    /// both add an action and `access_remove_action` one) — so it is exactly
    /// what the assistive technology was told.
    ///
    /// This is the gate on the `Action::Focus` walk into a subtree. A focusable
    /// leaf gets the action from `announce_focusable` and resolves to itself; a
    /// composite that keeps focus on an inner leaf and publishes its own node
    /// (`ComboBox`, `DateEdit` and its siblings) adds the action in its own
    /// `accessibility()` and means the walk. `SpinBox` publishes through its
    /// field instead, which is focusable and resolves to itself. Everything
    /// else (a `Panel`, a `GroupBox`, a landmark, a label) offers no `Focus`,
    /// and moving focus into it would land the keyboard on a descendant the
    /// assistive technology could have named itself and did not.
    pub(crate) fn advertises_focus_action(&self, id: WidgetId) -> bool {
        self.arena.get(id).is_some()
            && self
                .build_overridden_builder(id)
                .actions()
                .contains(&accesskit::Action::Focus)
    }

    pub(super) fn build_overridden_builder(&self, id: WidgetId) -> AccessNodeBuilder {
        use crate::widget_builder::AccessSubtreeMode;
        let node = self
            .arena
            .get(id)
            .expect("widget id is not in the arena (destroyed?)");
        // Every consumer of this builder reads scalars off it — role, name,
        // actions, the tri-state flags — and discards it. A name probe so a
        // text-bearing widget does not shape and emit runs nobody collects.
        let mut builder = AccessNodeBuilder::for_name_probe(id);
        node.widget.accessibility(&mut builder);
        self.announce_context_menu(id, &mut builder);
        self.announce_focusable(id, &mut builder);
        // The walker's rule, reached from the other end: it carries the
        // composites down to their proxy, this climbs from the node to them.
        if self.live_accessibility_proxy(id).is_none() {
            let behind = self.composites_standing_behind(id);
            for &composite in &behind {
                self.announce_context_menu(composite, &mut builder);
            }
            self.yield_default_name(id, &behind, &mut builder);
            self.apply_access_overrides(id, &mut builder);
            for composite in behind {
                self.apply_access_overrides(composite, &mut builder);
            }
        }
        if node.access_subtree == AccessSubtreeMode::Merge {
            merge_descendants_into(&mut builder, id, &self.arena);
        }
        builder
    }

    /// Drop a name the widget set with
    /// [`AccessNodeBuilder::set_default_name`] when a `labelled_by` relation
    /// on the node, or on a composite it stands for, names it instead.
    ///
    /// The naming order is the one Qt and WinUI follow: a name the
    /// application gave (`access_label`, `access_customize`, applied after
    /// this) first, then the label the node is linked to, then the control's
    /// built-in default. `accesskit_consumer` reads a node's own name before
    /// its `labelled_by` targets, so a default left in place would hide the
    /// row label of a `FormLayout`: a date field in a "Birthday" row read
    /// "Date". A relation whose targets are all gone or nameless names
    /// nothing, and then the default stays.
    fn yield_default_name(
        &self,
        id: WidgetId,
        standing_for: &[WidgetId],
        builder: &mut AccessNodeBuilder,
    ) {
        if !builder.name_is_default() {
            return;
        }
        let named_by_relation = std::iter::once(id)
            .chain(standing_for.iter().copied())
            .filter_map(|owner| self.arena.get(owner)?.access_overrides.as_deref())
            .flat_map(|ov| ov.labelled_by.iter().copied())
            .any(|target| self.has_name_to_give(target));
        if named_by_relation {
            builder.clear_default_name();
        }
    }

    /// Whether `target`, as the end of a `labelled_by` relation, gives the
    /// node pointing at it a name, read as `accesskit_consumer` reads it
    /// (`Node::write_label`): a `Role::Label` by its text, any other node by
    /// its own name alone, never by its own `labelled_by`.
    ///
    /// So a target that is not in the update (inactive, or under an excluded
    /// or merged ancestor) gives nothing, and neither does one whose own name
    /// is a default that yields to a relation of its own: the walk clears it,
    /// and the consumer does not follow that target's relation on. A relation
    /// that names a composite names the proxy standing for it (see
    /// `ProxyLedger::redirect_relations`), so the probe follows the proxy
    /// chain and applies the overrides the composites hand down.
    pub(crate) fn has_name_to_give(&self, target: WidgetId) -> bool {
        self.gives_name(target, &mut Vec::new())
    }

    fn gives_name(&self, target: WidgetId, visited: &mut Vec<WidgetId>) -> bool {
        use crate::widget_builder::AccessSubtreeMode;
        if !self.arena.is_active(target) || visited.contains(&target) {
            return false;
        }
        visited.push(target);
        // An excluded or merged subtree emits no node for the target.
        let mut ancestor = self.arena.parent(target);
        while let Some(a) = ancestor {
            if self
                .arena
                .get(a)
                .is_some_and(|n| n.access_subtree != AccessSubtreeMode::Inherit)
            {
                return false;
            }
            ancestor = self.arena.parent(a);
        }
        let mut node_id = target;
        // A proxy is a strict descendant, so the chain is finite; the bound
        // is a guard, not a limit anyone reaches.
        for _ in 0..16 {
            match self.live_accessibility_proxy(node_id) {
                Some(proxy) => node_id = proxy,
                None => break,
            }
        }
        let Some(node) = self.arena.get(node_id) else {
            return false;
        };
        let mut builder = AccessNodeBuilder::for_name_probe(node_id);
        node.widget.accessibility(&mut builder);
        let behind = self.composites_standing_behind(node_id);
        if builder.name_is_default() {
            let yields = std::iter::once(node_id)
                .chain(behind.iter().copied())
                .filter_map(|owner| self.arena.get(owner)?.access_overrides.as_deref())
                .flat_map(|ov| ov.labelled_by.clone())
                .any(|t| self.gives_name(t, visited));
            if yields {
                builder.clear_default_name();
            }
        }
        self.apply_access_overrides(node_id, &mut builder);
        for composite in behind {
            self.apply_access_overrides(composite, &mut builder);
        }
        let non_empty = |s: Option<&str>| s.is_some_and(|s| !s.trim().is_empty());
        if builder.role() == accesskit::Role::Label {
            // The walker writes a label's text as its value, which is what
            // the consumer reads from it.
            non_empty(builder.name()) || non_empty(builder.value())
        } else {
            non_empty(builder.name())
        }
    }

    /// Apply the builder-level overrides attached to `id` onto `builder`.
    ///
    /// `access_shortcut_id` is resolved here rather than in
    /// `AccessibilityOverrides::apply` because the override struct cannot reach
    /// the tree's `ShortcutRegistry`. Same mechanism as
    /// `MenuItem::for_shortcut(...)`: look up the effective primary keystroke
    /// and announce it through `KeyStroke`'s `Display`, or nothing when the id
    /// has no registered default.
    fn apply_access_overrides(&self, id: WidgetId, builder: &mut AccessNodeBuilder) {
        let Some(ov) = self
            .arena
            .get(id)
            .and_then(|node| node.access_overrides.as_deref())
        else {
            return;
        };
        ov.apply(builder);
        if let Some(ref sid) = ov.shortcut_id
            && let Some(eff) = self.shortcut_registry.effective(sid)
            && let Some(ks) = eff.primary
        {
            builder.set_keyboard_shortcut(ks.to_string());
        }
    }

    /// The descendant `id` hands its accessibility node to, if it names one
    /// the walk will honour: see [`Widget::accessibility_proxy`].
    ///
    /// A strict, live descendant that the walk reaches: `id` and every widget
    /// between the two walked normally. An excluded or merged subtree emits no
    /// node for the proxy to carry anything on, wherever it sits on the way
    /// down, so the overrides stay where they were attached.
    pub(crate) fn live_accessibility_proxy(&self, id: WidgetId) -> Option<WidgetId> {
        use crate::widget_builder::AccessSubtreeMode;
        let node = self.arena.get(id)?;
        if node.access_subtree != AccessSubtreeMode::Inherit {
            return None;
        }
        let proxy = node.widget.accessibility_proxy()?;
        if proxy == id || !self.arena.is_active(proxy) {
            return None;
        }
        // Climb from the proxy to `id`, which is the descendant check, and
        // refuse at the first widget in between that stops the walk.
        let mut current = self.arena.parent(proxy);
        while let Some(ancestor) = current {
            if ancestor == id {
                return Some(proxy);
            }
            if self.arena.get(ancestor)?.access_subtree != AccessSubtreeMode::Inherit {
                return None;
            }
            current = self.arena.parent(ancestor);
        }
        None
    }

    /// The composites whose node `id` stands for, innermost first: the order
    /// the walker applies their overrides in, so the outermost, which is the
    /// one an application attached last, wins.
    ///
    /// A composite can name another composite as its proxy, which names a
    /// field in turn, so the climb follows the chain rather than stopping at
    /// the first match.
    ///
    /// Two composites can also name the same proxy (a `DateEdit` and the
    /// `TextInput` inside it both name the field), so an ancestor counts when
    /// its proxy is `id` or any composite already found.
    pub(crate) fn composites_standing_behind(&self, id: WidgetId) -> Vec<WidgetId> {
        let mut found = Vec::new();
        let mut current = self.arena.parent(id);
        while let Some(ancestor) = current {
            if let Some(proxy) = self.live_accessibility_proxy(ancestor)
                && (proxy == id || found.contains(&proxy))
            {
                found.push(ancestor);
            }
            current = self.arena.parent(ancestor);
        }
        found
    }

    /// The composite an assistive `Focus` on `id` gives the keyboard to: the
    /// innermost focusable, enabled composite `id` stands for, when `id` is not
    /// focusable itself.
    ///
    /// An editor publishes its text on a body the keyboard never lands on, and
    /// that body is the node a screen reader sees, and the one it asks to
    /// focus. Parking the keyboard there would pass the keys up to the editor
    /// by bubbling but run none of its focus handlers, so no caret, no input
    /// method and no focus ring; and asking again while the editor holds focus
    /// would take focus away from it.
    ///
    /// Anything that gives the keyboard to a widget it found through the
    /// accessibility tree asks this first: the router does for an assistive
    /// `Focus`, and the automation toolkit does before it types.
    pub fn focusable_composite_behind(&self, id: WidgetId) -> Option<WidgetId> {
        if self
            .arena
            .get(id)
            .is_none_or(|node| self.is_node_focusable(node))
        {
            return None;
        }
        self.composites_standing_behind(id)
            .into_iter()
            .find(|&composite| {
                self.arena.is_enabled(composite)
                    && self
                        .arena
                        .get(composite)
                        .is_some_and(|node| self.is_node_focusable(node))
            })
    }

    /// The `access_disabled` override in force on `id`'s node: its own, unless
    /// it handed its node to a proxy, then those of the composites it stands
    /// for, the last one set winning as it does for every scalar override.
    pub(crate) fn access_disabled_override(
        &self,
        id: WidgetId,
        handed_on: bool,
        standing_for: &[WidgetId],
    ) -> Option<bool> {
        if handed_on {
            return None;
        }
        std::iter::once(id)
            .chain(standing_for.iter().copied())
            .filter_map(|w| {
                self.arena
                    .get(w)
                    .and_then(|node| node.access_overrides.as_deref())
                    .and_then(|ov| ov.disabled)
            })
            .last()
    }

    /// The tooltip a composite that hands its node to a proxy should hand on
    /// with it: the one it owns, when it owns exactly one, or else one
    /// anchored on it. The same claim `tooltip_description_target` grants an
    /// owner, without the checks on the node, which are the proxy's to pass.
    fn tooltip_claim_for_proxy(
        &self,
        id: WidgetId,
        handled: &std::collections::HashSet<WidgetId>,
    ) -> Option<WidgetId> {
        let mut claims = self
            .tooltips
            .iter()
            .filter(|t| t.description_owner_id == id && !handled.contains(&t.content_id));
        if let (Some(only), None) = (claims.next(), claims.next()) {
            return Some(only.content_id);
        }
        self.tooltips
            .iter()
            .find(|t| t.anchor_id == id && !handled.contains(&t.content_id))
            .map(|t| t.content_id)
    }
}

/// What composites hand down, during one walk, to the descendants that stand
/// for them in the accessibility tree ([`Widget::accessibility_proxy`]).
///
/// The walk visits a composite before its proxy, so the composite leaves its
/// share here and the proxy collects it when the walk arrives.
#[derive(Default)]
pub(super) struct ProxyLedger {
    /// For each proxy, the composites it stands for, innermost first.
    standing_for: std::collections::HashMap<WidgetId, Vec<WidgetId>>,
    /// The tooltip a composite owned, kept for its proxy.
    tooltips: std::collections::HashMap<WidgetId, WidgetId>,
    /// Each composite's node, and the node of the proxy standing for it.
    nodes: std::collections::HashMap<accesskit::NodeId, accesskit::NodeId>,
}

impl ProxyLedger {
    /// The node standing for `nid`, through any chain of composites: `nid`
    /// itself when no composite handed it on.
    fn stand_in(&self, mut nid: accesskit::NodeId) -> accesskit::NodeId {
        // A proxy is a strict descendant, so a chain never loops; the bound is
        // there so that cannot be assumed.
        for _ in 0..self.nodes.len() {
            match self.nodes.get(&nid) {
                Some(&next) => nid = next,
                None => break,
            }
        }
        nid
    }

    /// Point every `controls`, `described_by` and `labelled_by` target that
    /// names a composite at the node standing for it, through any chain of
    /// composites.
    fn redirect_relations(&self, nodes: &mut [(accesskit::NodeId, accesskit::Node)]) {
        if self.nodes.is_empty() {
            return;
        }
        let redirected = |ids: &[accesskit::NodeId]| {
            ids.iter()
                .any(|id| self.nodes.contains_key(id))
                .then(|| ids.iter().map(|&id| self.stand_in(id)).collect::<Vec<_>>())
        };
        for (_, node) in nodes.iter_mut() {
            if let Some(ids) = redirected(node.controls()) {
                node.set_controls(ids);
            }
            if let Some(ids) = redirected(node.described_by()) {
                node.set_described_by(ids);
            }
            if let Some(ids) = redirected(node.labelled_by()) {
                node.set_labelled_by(ids);
            }
        }
    }
}

/// Whether an AT node is a purely-structural container that should be
/// collapsed out of the tree (its children promoted to its parent).
///
/// True only for a content-free `GenericContainer` / `Unknown` node — the
/// empty boxes layout primitives (HStack/VStack/Padding/Expand/…) emit.
/// The check is exhaustive by construction: set aside the framework-applied
/// children, bounds, and disabled flag, then compare against a fresh
/// default node of the same role. Any author- or widget-set property —
/// name, value, description, orientation, aria-current, identifier, live
/// region, popup, action, relation, hidden flag, … — makes the node differ
/// from the default and keeps it, so no semantic property can be missed.
/// Callers additionally exempt the Window root, the focused node, and
/// relationship targets.
fn is_presentational_container(node: &accesskit::Node) -> bool {
    use accesskit::Role;
    if !matches!(node.role(), Role::GenericContainer | Role::Unknown) {
        return false;
    }
    // Set aside the framework-applied structural bits (children, bounds,
    // arena-driven disabled flag), then check the node carries no semantic
    // content by comparing against a bare node of the same role.
    //
    // We compare the *Debug* form, not `==`: AccessKit's `clear_*` leaves
    // residue in the private property-value vec (the index is unset but the
    // value stays), so `PartialEq` never matches a fresh node. `Node`'s
    // Debug renders only logically-set properties, so it reflects true
    // content and is exhaustive — any author/widget property keeps the node.
    let mut probe = node.clone();
    probe.clear_children();
    probe.clear_bounds();
    probe.clear_disabled();
    format!("{probe:?}") == format!("{:?}", accesskit::Node::new(node.role()))
}

// ─────────────────────────────────────────────────────────────────────
// Subtree-merge helpers
// ─────────────────────────────────────────────────────────────────────
//
// These run when a widget's `access_subtree` is `Merge`. The walker
// recurses through the descendants, applies each descendant's own
// `accessibility() + override apply()` into a temp builder, and absorbs
// the resulting label / value / actions into a `MergeAccumulator`.
// After the walk finishes the accumulator flushes its accumulated state
// onto the parent's builder.
//
// The accumulator deliberately discards descendant role and numeric
// fields (parent's role wins for the merged element) and discards
// disabled (parent's state governs the whole merged subtree). A hidden
// descendant is not merged at all, and neither is its subtree.
// Action lists union with deduplication so two child Buttons each
// emitting `Click` don't pollute the merged parent with two copies.

/// Walk the descendants of `parent_id` and absorb their label / value /
/// actions into `parent_builder`. Per-descendant subtree-mode handling
/// lives in [`merge_collect_recursive`].
fn merge_descendants_into(
    parent_builder: &mut AccessNodeBuilder,
    parent_id: WidgetId,
    arena: &crate::arena::WidgetArena,
) {
    let mut acc = MergeAccumulator::default();
    for &child in arena.children(parent_id) {
        merge_collect_recursive(child, arena, &mut acc);
    }
    acc.flush_into(parent_builder);
}

fn merge_collect_recursive(
    id: WidgetId,
    arena: &crate::arena::WidgetArena,
    acc: &mut MergeAccumulator,
) {
    use crate::widget_builder::AccessSubtreeMode;

    if !arena.is_active(id) {
        return;
    }
    let Some(node) = arena.get(id) else {
        return;
    };

    // Build a temp builder for this descendant the same way the walker
    // would: widget.accessibility() then override apply(). This means
    // a descendant's `.access_label(...)` contributes its resolved
    // override string, not its raw widget label.
    // A name probe: `absorb` takes the descendant's name, value, actions and
    // relations, never its synthetic children — and the runs a text widget
    // would emit here would be discarded with `tmp` while the widget's own
    // node keeps its copies.
    let mut tmp = AccessNodeBuilder::for_name_probe(id);
    node.widget.accessibility(&mut tmp);
    if let Some(ov) = node.access_overrides.as_deref() {
        ov.apply(&mut tmp);
    }
    // Nested-merge: the descendant itself has access_subtree=Merge.
    // Run its own merge into `tmp` BEFORE absorbing — otherwise we'd
    // absorb the descendant's empty container state and lose its
    // subtree-merged label.
    if matches!(node.access_subtree, AccessSubtreeMode::Merge) {
        merge_descendants_into(&mut tmp, id, arena);
    }
    // Skip nodes that opted out of AT entirely: a child marked
    // `access_hidden(true)` (or whose widget called `set_hidden()`)
    // contributes nothing to the merge, and neither does anything under it.
    // The consumer the adapters read through treats a node as hidden when
    // any ancestor is, so text below a hidden node is text the widget hid;
    // merging it would say it aloud on the merged node.
    if tmp.is_hidden() {
        return;
    }
    acc.absorb(&tmp);

    match node.access_subtree {
        AccessSubtreeMode::Exclude => {
            // Prune — don't recurse into descendants of an excluded subtree.
        }
        AccessSubtreeMode::Merge => {
            // Nested Merge: descendant's own subtree was absorbed into
            // `tmp` above; don't re-walk its children at this level
            // (would double-count). The descendant reads as one
            // AT element from the outer merge's perspective.
        }
        AccessSubtreeMode::Inherit => {
            for &grandchild in arena.children(id) {
                merge_collect_recursive(grandchild, arena, acc);
            }
        }
    }
}

/// Per-merge-walk accumulator. Collects descendant state across the
/// recursive walk, then `flush_into` writes the unioned values onto
/// the parent's builder.
///
/// Fields that the absorb path can read from `AccessNodeBuilder`
/// (label, value, advertised actions) participate in the merge.
/// Description and relationship lists (`controls` / `described_by` /
/// `labelled_by`) live inside `accesskit::Node` and have no public
/// getter on `AccessNodeBuilder`; merging them would require
/// reflecting builder mutations into a parallel field, which we
/// haven't found a real-world use case for. App authors who need
/// description / relationship merge can use the `access_customize`
/// escape hatch on the parent.
#[derive(Default)]
struct MergeAccumulator {
    label_parts: Vec<String>,
    /// First non-empty value wins.
    value: Option<String>,
    actions: Vec<accesskit::Action>,
}

impl MergeAccumulator {
    fn absorb(&mut self, src: &AccessNodeBuilder) {
        if let Some(name) = src.name()
            && !name.is_empty()
        {
            self.label_parts.push(name.to_string());
        }
        if let Some(value) = src.value()
            && self.value.is_none()
            && !value.is_empty()
        {
            self.value = Some(value.to_string());
        }
        for &action in src.actions() {
            if !self.actions.contains(&action) {
                self.actions.push(action);
            }
        }
    }

    fn flush_into(self, dst: &mut AccessNodeBuilder) {
        // Concatenate new label parts onto whatever the parent's
        // builder already carried. Existing parent name kept first.
        if !self.label_parts.is_empty() {
            let existing = dst.name().map(|s| s.to_string());
            let merged = match existing {
                Some(e) if !e.is_empty() => {
                    let mut s = e;
                    for part in self.label_parts {
                        s.push(' ');
                        s.push_str(&part);
                    }
                    s
                }
                _ => self.label_parts.join(" "),
            };
            dst.set_name(merged);
        }
        if let Some(v) = self.value {
            // Only overwrite parent value if it's currently None — the
            // parent's own value (from the inner widget or override
            // `access_value`) takes precedence.
            if dst.value().is_none() {
                dst.set_value(v);
            }
        }
        for action in self.actions {
            // Union: skip actions already advertised on the parent
            // (avoid duplicate Click/Focus when parent is itself a Button).
            if !dst.actions().contains(&action) {
                dst.add_action(action);
            }
        }
    }
}