teksilo_core/

accessibility.rs

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

use accesskit::{Action, Live, Node, NodeId, Role, TextDirection, TextPosition, TextSelection};

use crate::widget_id::WidgetId;

pub(crate) mod adapter_ids;
pub(crate) mod announcements;
pub mod audit;
pub mod target_audit;
pub mod text_runs;

/// Builder wrapper around accesskit::Node for widget accessibility declarations.
pub struct AccessNodeBuilder {
    inner: Node,
    name: Option<String>,
    value: Option<String>,
    role: Role,
    actions: Vec<Action>,
    toggled: Option<bool>,
    expanded: Option<bool>,
    selected: Option<bool>,
    hidden: bool,
    /// The owning widget's id. Set at construction time by the
    /// tree walker (via `AccessNodeBuilder::for_widget`). Used by
    /// the sub-tree API (`push_paragraph_child` / `push_text_run_child`)
    /// to derive synthetic NodeIds without asking the caller to
    /// pass the WidgetId at every call site.
    owner: Option<WidgetId>,
    /// Pending text selection targeting the widget's own node id.
    /// Resolved at `build(id)` time because the widget doesn't know
    /// its node id during `accessibility(&self, builder)`.
    pending_self_selection: Option<(usize, usize)>,
    /// Deferred text selection targeting synthetic child NodeIds
    /// (TextRuns). Unlike `pending_self_selection`, these
    /// TextPositions reference NodeIds that are already known at
    /// the time the widget calls `set_text_selection_to`, so we
    /// can populate the selection during `build(id)` directly —
    /// the field just holds them until that point.
    pending_explicit_selection: Option<(TextPosition, TextPosition)>,
    /// Synthetic child nodes emitted by the widget via
    /// `push_paragraph_child` / `push_text_run_child`. Drained by
    /// the tree walker after `Widget::accessibility(&self, builder)`
    /// returns and merged into the full AccessKit `TreeUpdate`.
    children_collected: Vec<(NodeId, Node)>,
    /// Bounds a widget declared for its synthetic children in **its own**
    /// coordinate space, translated into window space by [`build`] —
    /// which is the first moment the owner's absolute rect is known,
    /// because the walker writes it onto the node just before calling.
    ///
    /// A widget that already holds absolute rects (a scene item, a
    /// composite emitting geometry it got from a child it placed) calls
    /// `set_bounds` on the child node directly and never appears here.
    ///
    /// [`build`]: AccessNodeBuilder::build
    child_local_bounds: Vec<(NodeId, teksilo_canvas::Rect)>,
    /// This builder exists only to harvest an accessible *name* — the
    /// merge pass and the tooltip-description probe both run a widget's
    /// `accessibility()` on a throwaway builder and read nothing but the
    /// name off it. Emitting synthetic children there would allocate
    /// node ids that never reach the tree, and, worse, would be
    /// discarded along with the builder while the widget's real node
    /// keeps its own copies.
    name_probe: bool,
}

/// The ids of every `Role::TextRun` this node attached to **itself**, or
/// `None` when there are none.
///
/// Scoped to the node's own child list on purpose. A builder's collected
/// vector also holds *grandchildren* — a scene item is emitted through a
/// nested builder whose whole subtree is folded into the outer one — and
/// those belong to a parent of their own, which may well be a
/// `Role::Label` that does support ranges. Dropping them because the
/// *outer* node cannot carry runs would delete nodes the item's own
/// children list still names, and `accesskit_consumer` panics on a
/// child id that reaches no node.
fn own_run_ids(
    inner: &Node,
    children: &[(NodeId, Node)],
) -> Option<std::collections::HashSet<NodeId>> {
    let attached: std::collections::HashSet<NodeId> = inner.children().iter().copied().collect();
    let ids: std::collections::HashSet<NodeId> = children
        .iter()
        .filter(|(id, node)| node.role() == Role::TextRun && attached.contains(id))
        .map(|(id, _)| *id)
        .collect();
    (!ids.is_empty()).then_some(ids)
}

/// Everything one `Role::TextRun` node needs.
#[derive(Debug, Clone)]
pub struct TextRunSpec {
    /// Mixed with the owner and the run kind to derive the node id.
    pub element_id: u64,
    pub value: String,
    /// UTF-8 byte length of each character of `value`. Their sum must be
    /// `value.len()`; AccessKit panics otherwise.
    pub character_lengths: Vec<u8>,
    pub word_starts: Vec<u8>,
    pub character_positions: Vec<f32>,
    pub character_widths: Vec<f32>,
    pub bounds: teksilo_canvas::Rect,
    /// `true` when `bounds` is already in window space.
    pub bounds_are_absolute: bool,
    pub text_direction: TextDirection,
    pub attrs: TextRunAttributes,
}

/// A Teksilo affine as AccessKit expresses one.
///
/// Both store a 3×2 matrix mapping `(x, y)` to
/// `(a·x + c·y + tx, b·x + d·y + ty)`, and both spell it `[a, b, c, d, tx, ty]`,
/// so this is a widening cast and not a change of convention.
///
/// Write the result with [`accesskit::Node::set_transform`] on a node whose
/// own bounds — and every rectangle below it — are stated in a coordinate
/// space of its own rather than in window space. That is the one supported way
/// to publish such a rectangle: a consumer reads `bounds` "in the coordinate
/// space of the nearest ancestor with a non-`None` transform", composes the
/// chain for `bounding_box()`, and inverts it per step when hit-testing, so
/// projecting by hand instead would be exact only for the rectangle and wrong
/// for the per-character geometry and the hit path.
///
/// The framework does this for the children of a content-transform node (see
/// `WidgetTree::build_accessibility_recursive`); a widget emitting synthetic
/// children of its own in a non-window space — a scene item, a chart mark —
/// calls it directly.
pub fn to_accesskit_affine(t: teksilo_canvas::Transform2D) -> accesskit::Affine {
    let [a, b, c, d, tx, ty] = t.m;
    accesskit::Affine::new([a as f64, b as f64, c as f64, d as f64, tx as f64, ty as f64])
}

/// The text a node announces as its name, read the way every platform adapter
/// reads it.
///
/// A `Role::Label` carries its text in `value`, not `label` — Windows UIA
/// derives the Name from `value` for that role, macOS exposes it as
/// `AXValue`, and `accesskit_consumer` reads `value` when another control is
/// `labelled_by` it. `AccessNodeBuilder::build` moves it there. Everything
/// else carries its name in `label`. A test or probe that reads one property
/// sees nothing on half the tree.
///
/// Neither falls back to the other. The AT-SPI, UIA and macOS adapters all
/// take the name from `label_comes_from_value() ? value : label`
/// (`accesskit_atspi_common` `node.rs:38-44`, `accesskit_windows`
/// `node.rs:404-413`, `accesskit_macos` `node.rs:328-334`, with
/// `label_comes_from_value` true for `Role::Label` alone, consumer
/// `node.rs:744-746`), so a `Status` that holds its text only as a value has
/// no name, and no platform announces it as one. This reads one node's own
/// properties: a name that comes through `labelled_by` takes the consumer's
/// `NodeRef::label` to follow.
pub fn announced_text(node: &Node) -> Option<&str> {
    if node.role() == Role::Label {
        node.value()
    } else {
        node.label()
    }
}

/// Whether a node with this role can carry text ranges at all.
///
/// `accesskit_consumer::Node::supports_text_ranges` is
/// `(is_text_input || role ∈ {Label, Document, Terminal}) && has runs`
/// (`accesskit_consumer-0.39.0/src/text.rs:1402`). Runs under any other
/// role are inert: no platform exposes them, and they still cost a node
/// in every update.
pub fn role_supports_text_ranges(role: Role) -> bool {
    matches!(
        role,
        Role::Label
            | Role::Document
            | Role::Terminal
            | Role::TextInput
            | Role::MultilineTextInput
            | Role::SearchInput
            | Role::DateInput
            | Role::DateTimeInput
            | Role::WeekInput
            | Role::MonthInput
            | Role::TimeInput
            | Role::EmailInput
            | Role::NumberInput
            | Role::PasswordInput
            | Role::PhoneNumberInput
            | Role::UrlInput
            | Role::EditableComboBox
            | Role::SpinButton
    )
}

/// Discriminator kind for synthetic-NodeId hashing. Different
/// kinds sharing the same (widget_id, element_id) tuple produce
/// distinct NodeIds so paragraph and run nodes for the same
/// source element don't collide.
#[derive(Debug, Clone, Copy)]
#[repr(u8)]
pub enum SyntheticKind {
    Paragraph = 1,
    TextRun = 2,
    ImageRun = 3,
    /// An inline link span inside a label-style widget's text
    /// (e.g. `[docs](url)` inside a TextWidget with `.markup(true)`
    /// enabled). Each link span becomes one synthetic child of the
    /// hosting widget's own node, with `Role::Link` and the link label
    /// as its name.
    Link = 4,
    /// A lightweight `SceneItem` rendered by `teksilo_scene::SceneView`.
    /// Items live outside the arena — `SceneView::accessibility`
    /// emits one synthetic child per visible item using
    /// `push_scene_child`.
    SceneItem = 5,
    /// A logical grouping declared via `Scene::add_a11y_group`.
    /// Pure AT structure — no visual counterpart. The parent's
    /// children list orders mixed `SceneItem` and `SceneGroup`
    /// synthetic NodeIds however the app declared the logical tree.
    SceneGroup = 6,
    /// A magnetism anchor ("magnet") attached to a scene item. Emitted
    /// as a synthetic child of the owning item's node by
    /// `SceneView::accessibility` when magnetism is enabled, so the
    /// anchor is screen-reader perceivable and can be the target of the
    /// view's `active_descendant` during the keyboard connect flow.
    SceneMagnet = 7,
    /// A per-datum mark (bar / line point / pie slice) emitted by a
    /// `teksilo-charts` widget's `accessibility()`.
    ChartMark = 8,
    /// An annotation body (a comment thread) attached to a run of text, emitted
    /// by a rich-text widget alongside the `TextRun` that carries it. The run
    /// points at this node through the `details` relation — AccessKit's
    /// `aria-details` — which is what lets a screen reader say "has comment" and
    /// let the user navigate in, rather than reciting the thread inline every
    /// time the caret crosses the span.
    Annotation = 9,
    /// A positional mark in a margin lane — the strip beside a scroll area that
    /// maps where things are in a document rather than picturing it.
    ///
    /// Emitted by the lane widget's `accessibility()`, one synthetic child per
    /// mark, the same shape [`SyntheticKind::ChartMark`] uses per datum. Marks
    /// get their own nodes, rather than riding the content they refer to, for
    /// the reason `CodeGutter` gives for *not* doing so: line numbers are
    /// uniform, dense and derivable from the text, so they belong on the
    /// paragraph node as `position_in_set`; lane marks are sparse, heterogeneous
    /// and not derivable from anything — "a comment from Marie at 62 percent" is
    /// not in the paragraph, so there is no node to delegate to.
    LaneMark = 10,
    /// The selection transform frame and its handles, emitted by
    /// `teksilo_scene::SceneView` when a transform controller is installed.
    ///
    /// One frame node per *view* plus at most nine handle nodes hang off it —
    /// not one per item — because the frame belongs to the selection rather
    /// than to any item, and a multi-item selection has no owner. The handles
    /// are a paint pass, never scene items, so they add nothing to the item
    /// walk, to `items_in_rect`, or to a marquee's result.
    SceneHandle = 11,
    /// A table inside a rich-text document, emitted by the rich-text
    /// accessibility walk from a `FlowElementSnapshot::Table`. Keyed by the
    /// document's own `table_id`, so the node survives every edit that does
    /// not destroy the table.
    RichTextTable = 12,
    /// One row of a [`SyntheticKind::RichTextTable`], keyed by the table and
    /// the row index together.
    RichTextTableRow = 13,
    /// One cell of a [`SyntheticKind::RichTextTable`], keyed by the table and
    /// the cell's row and column together.
    RichTextTableCell = 14,
    /// The text container inside a [`SyntheticKind::RichTextTableCell`].
    ///
    /// A cell's text runs cannot hang off the cell directly. The platform
    /// adapters route a changed run's text-change event to its *filtered*
    /// parent, and `accesskit_consumer`'s `common_filter` makes only
    /// `GenericContainer` and `TextRun` transparent — so a `Role::Cell`
    /// parent is asked whether it `supports_text_ranges()`, answers no, and
    /// every keystroke typed into the cell is dropped before it reaches a
    /// screen reader. This node is the `Role::Label` between the two: it is
    /// text-range capable, so the event survives, and it is what a reader
    /// announces as the cell's content.
    RichTextCellText = 15,
    /// The text container inside a structural block-level node — a
    /// `Role::Heading`, or a `Role::Blockquote`.
    ///
    /// Exactly the problem [`SyntheticKind::RichTextCellText`] solves, in the
    /// other places a structural node sits between the editor and its runs:
    /// neither role is text-range capable, so runs parented straight onto one
    /// had every edit beneath it dropped before it reached a screen reader.
    /// Keyed by the **block's** own id — one per block, so a heading inside a
    /// blockquote still has exactly one — which is a different id space from a
    /// cell's packed `(table, row, column)`, so the two kinds stay distinct
    /// rather than relying on those spaces never colliding.
    RichTextBlockText = 16,
    /// A blockquote in a rich-text document, emitted from a
    /// `FlowElementSnapshot::Frame` whose `FrameFormat::is_blockquote` is set.
    ///
    /// Only a blockquote earns a node. A frame is otherwise a layout box — a
    /// positioned or floating text frame — with no role to announce, and
    /// wrapping one in a node a reader stops on would be AT noise.
    RichTextBlockquote = 17,
}

/// A live-region announcement every platform adapter would have made.
///
/// Teksilo has no OS accessibility layer in headless mode, and even with
/// one there is no in-process way to observe what the platform *spoke*.
/// So a tree that [records announcements](crate::WidgetTree::records_announcements)
/// replays every update [`crate::WidgetTree::sync_accessibility`] returns
/// through `accesskit_consumer`, the diff the AT-SPI, Windows and
/// macOS adapters are all built on, and the announcements those adapters
/// would raise are kept in a ring that an automation or test harness drains
/// through [`crate::WidgetTree::announcements_since`]: a live node entering
/// the filtered tree with a name, or a live node in it whose name changed.
/// A live node the adapters cannot hear, because it is hidden, inside a
/// hidden subtree, or carries its text as a `value` where its role takes a
/// label, is not in the ring. This models what the adapters hand a screen
/// reader, not what the screen reader then says, so it does not replace
/// listening to one.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Announcement {
    /// Monotonic sequence number, starting at 1. `announcements_since(n)`
    /// returns every announcement whose `seq > n`.
    pub seq: u64,
    /// The node's name as every adapter computes it, which is the string the
    /// platform announces: the `value` of a `Role::Label`, the label of any
    /// other role, followed through `labelled_by` when the node has none of
    /// its own.
    pub text: String,
    /// `true` for `Live::Assertive`, `false` for `Live::Polite`. A node with
    /// no setting of its own takes its nearest live ancestor's, as the
    /// adapters do.
    pub assertive: bool,
}

/// Top bit of the u64 NodeId encoding. Set for synthetic (widget-
/// emitted child) NodeIds, clear for widget-derived NodeIds.
/// Slotmap-derived WidgetIds never set bit 63 in practice because
/// slotmap's KeyData encoding occupies bits 32-63 with a version
/// counter that starts at 1.
pub(crate) const SYNTHETIC_BIT: u64 = 1u64 << 63;

/// Stable hash of (parent widget, element id, kind) producing a
/// synthetic NodeId that survives edits for as long as the
/// underlying element id is stable. Used by `AccessNodeBuilder`'s
/// sub-tree API to allocate NodeIds for paragraph / text-run
/// children without colliding with widget-derived NodeIds.
pub fn synthetic_node_id(parent: WidgetId, element_id: u64, kind: SyntheticKind) -> NodeId {
    use slotmap::Key;
    let parent_raw = parent.data().as_ffi();
    let h = fnv_mix_u64(parent_raw, element_id, kind as u64);
    NodeId((h & !SYNTHETIC_BIT) | SYNTHETIC_BIT)
}

/// Convert an ARIA-style **1-based** ordinal to the **zero-based** integer
/// AccessKit stores.
///
/// AccessKit deliberately departs from ARIA on four properties, and says so in
/// its own documentation (`accesskit-0.25.0/src/lib.rs`, each carrying a
/// "**Difference with ARIA**" paragraph):
///
/// | property | ARIA | AccessKit |
/// |---|---|---|
/// | `position_in_set` / `aria-posinset` | 1-based | **0-based** |
/// | `row_index` / `aria-rowindex` | 1-based | **0-based** |
/// | `column_index` / `aria-colindex` | 1-based | **0-based** |
/// | `level` / `aria-level` | 1-based | **0-based** |
///
/// Two of the three platform adapters add the 1 back before handing the value
/// to the platform — `accesskit_windows-0.35.0/src/node.rs:682-687` and
/// `:698-701`, `accesskit_atspi_common-0.20.0/src/node.rs:394` — so writing an
/// ARIA-shaped number straight through lands one too high in what the screen
/// reader actually says. `accesskit_macos-0.27.0` reads none of the four, so
/// the error is invisible there, which is part of why it went unnoticed.
///
/// Teksilo's public surface stays 1-based, because that is the convention every
/// call site, every doc comment and ARIA itself already use, and because "the
/// first tab is tab 1" is what the value means to a person. The conversion
/// happens once, here, at the boundary.
///
/// Saturating rather than panicking on 0: an off-by-one in a caller should
/// produce a slightly wrong announcement, not take down the application. A
/// caller that passes 0 gets the same node it would have got for 1.
fn to_accesskit_ordinal(one_based: usize) -> usize {
    debug_assert!(
        one_based >= 1,
        "AccessKit ordinals are 1-based at this boundary; 0 is not a position, \
         row, column or level"
    );
    one_based.saturating_sub(1)
}

/// Whether a given `NodeId` is a synthetic child node (emitted by a
/// widget via `push_paragraph_child` / `push_text_run_child`) rather
/// than a widget-derived NodeId.
pub fn is_synthetic(id: NodeId) -> bool {
    id.0 & SYNTHETIC_BIT != 0
}

/// FNV-1a-inspired 64-bit mixer for three u64 inputs. Not a
/// cryptographic hash — just a fast, deterministic, well-distributed
/// mix for collision-free synthetic NodeIds across the
/// (widget, element, kind) space.
pub(crate) fn fnv_mix_u64(a: u64, b: u64, c: u64) -> u64 {
    const FNV_OFFSET: u64 = 0xcbf29ce484222325;
    const FNV_PRIME: u64 = 0x100000001b3;
    let mut h = FNV_OFFSET;
    for byte in a
        .to_le_bytes()
        .iter()
        .chain(b.to_le_bytes().iter())
        .chain(c.to_le_bytes().iter())
    {
        h ^= *byte as u64;
        h = h.wrapping_mul(FNV_PRIME);
    }
    h
}

/// Styling attributes surfaced to assistive technology on a synthetic
/// `Role::TextRun` node (WCAG 1.3.1 Info and Relationships / EN 301 549
/// 11.5.2.9 "text attributes"). All fields default to "unset"; a rich-text
/// widget populates them per formatting run so a screen reader can convey
/// bold / italic / underline / strikethrough spans. AccessKit has no
/// dedicated `bold` property, so [`bold`](Self::bold) folds into
/// `set_font_weight(700)` when no explicit [`font_weight`](Self::font_weight)
/// is given.
#[derive(Debug, Clone, Copy, Default)]
pub struct TextRunAttributes {
    /// Explicit numeric font weight (`100..=900`). Takes precedence over
    /// [`bold`](Self::bold).
    pub font_weight: Option<u16>,
    /// Bold flag; folded to weight `700` when `font_weight` is `None`.
    pub bold: bool,
    pub italic: bool,
    pub underline: bool,
    pub strikethrough: bool,
}

/// Apply a run's formatting to its node.
///
/// WCAG 1.3.1 / EN 301 549 11.5.2.9. AccessKit has no bold flag, so an
/// explicit weight wins and a bare `bold` folds to 700.
fn apply_run_attrs(node: &mut Node, attrs: TextRunAttributes) {
    if let Some(weight) = attrs.font_weight {
        node.set_font_weight(weight as f32);
    } else if attrs.bold {
        node.set_font_weight(700.0);
    }
    if attrs.italic {
        node.set_italic();
    }
    if attrs.underline {
        node.set_underline(default_text_decoration());
    }
    if attrs.strikethrough {
        node.set_strikethrough(default_text_decoration());
    }
}

/// The `TextDecoration` used for underline / strikethrough on a text run.
/// Screen readers key off the *presence* of a decoration, not its colour,
/// so a solid neutral (black) decoration is sufficient; the run's own
/// foreground colour is not plumbed through this synthetic-node path.
fn default_text_decoration() -> accesskit::TextDecoration {
    accesskit::TextDecoration {
        style: accesskit::TextDecorationStyle::Solid,
        color: accesskit::Color {
            red: 0,
            green: 0,
            blue: 0,
            alpha: 255,
        },
    }
}

impl AccessNodeBuilder {
    pub fn new() -> Self {
        Self {
            inner: Node::new(Role::Unknown),
            name: None,
            value: None,
            role: Role::Unknown,
            actions: Vec::new(),
            toggled: None,
            expanded: None,
            selected: None,
            hidden: false,
            owner: None,
            pending_self_selection: None,
            pending_explicit_selection: None,
            children_collected: Vec::new(),
            child_local_bounds: Vec::new(),
            name_probe: false,
        }
    }

    /// Construct a builder with a known owner WidgetId. Used by the
    /// tree walker when invoking `Widget::accessibility`; the owner
    /// id drives synthetic NodeId derivation in the sub-tree API.
    pub fn for_widget(owner: WidgetId) -> Self {
        let mut b = Self::new();
        b.owner = Some(owner);
        b
    }

    /// A builder whose only purpose is to harvest a widget's accessible
    /// *name*.
    ///
    /// The merge pass (`AccessSubtreeMode::Merge`) and the
    /// tooltip-description probe both run a widget's `accessibility()`
    /// against a throwaway builder and read nothing off it but the name.
    /// Text runs must not be emitted there: their node ids would never
    /// reach the tree, and the run-emitting helpers still need to compute
    /// the merged text so the *name* comes out right.
    pub fn for_name_probe(owner: WidgetId) -> Self {
        let mut b = Self::for_widget(owner);
        b.name_probe = true;
        b
    }

    /// Whether this builder is a name probe (see
    /// [`for_name_probe`](Self::for_name_probe)), or has no owner at all —
    /// the two cases in which a widget must emit no synthetic children.
    ///
    /// An owner-less builder is a legitimate, if unusual, caller: the
    /// overlay measurement path and the debug inspector both run
    /// `accessibility()` on an arbitrary widget through
    /// [`AccessNodeBuilder::new`] to read its role and name.
    pub fn emits_no_children(&self) -> bool {
        self.name_probe || self.owner.is_none()
    }

    pub fn set_role(&mut self, role: Role) {
        self.role = role;
        self.inner.set_role(role);
    }

    pub fn set_name(&mut self, name: impl Into<String>) {
        let name: String = name.into();
        self.inner.set_label(name.clone());
        self.name = Some(name);
    }

    pub fn set_disabled(&mut self) {
        self.inner.set_disabled();
    }

    /// Clear the disabled flag set by an earlier `set_disabled()` call. Used
    /// by the override layer to un-set state a widget emitted unconditionally
    /// (e.g. a Panel that always calls `set_hidden`/`set_disabled`).
    pub fn clear_disabled(&mut self) {
        self.inner.clear_disabled();
    }

    pub fn add_action(&mut self, action: Action) {
        self.inner.add_action(action);
        self.actions.push(action);
    }

    /// Remove a previously-advertised action. Used by the override layer
    /// (`access_remove_action`) to suppress an action a widget emitted but
    /// that doesn't apply in this composition.
    pub fn remove_action(&mut self, action: Action) {
        self.inner.remove_action(action);
        self.actions.retain(|a| *a != action);
    }

    pub fn set_value(&mut self, value: impl Into<String>) {
        let v: String = value.into();
        self.inner.set_value(v.clone());
        self.value = Some(v);
    }

    /// Advertise a color value on this node — typically paired with
    /// [`accesskit::Role::ColorWell`]. Takes a `teksilo_tokens::Color` (f32
    /// channels) and quantizes to AccessKit's 8-bit `Color` representation.
    pub fn set_color_value(&mut self, color: teksilo_tokens::Color) {
        let ak = accesskit::Color {
            red: (color.r() * 255.0).round().clamp(0.0, 255.0) as u8,
            green: (color.g() * 255.0).round().clamp(0.0, 255.0) as u8,
            blue: (color.b() * 255.0).round().clamp(0.0, 255.0) as u8,
            alpha: (color.a() * 255.0).round().clamp(0.0, 255.0) as u8,
        };
        self.inner.set_color_value(ak);
    }

    pub fn set_description(&mut self, description: impl Into<String>) {
        self.inner.set_description(description.into());
    }

    pub fn set_live(&mut self, live: Live) {
        self.inner.set_live(live);
    }

    pub fn set_described_by(&mut self, ids: impl Into<Vec<NodeId>>) {
        self.inner.set_described_by(ids);
    }

    /// Append one node to the `described_by` relationship list. Mirror of
    /// the existing `push_controlled`; used by the override layer's
    /// `access_described_by` builder method and by the framework's
    /// tooltip wiring. The relation by itself reaches no screen reader
    /// through AccessKit 0.25; the tree writes each target's text into the
    /// node's description when it builds the update.
    pub fn push_described_by(&mut self, id: NodeId) {
        self.inner.push_described_by(id);
    }

    /// Append one node to the `labelled_by` relationship list. Used by
    /// `access_labelled_by` to point at an external label widget.
    pub fn push_labelled_by(&mut self, id: NodeId) {
        self.inner.push_labelled_by(id);
    }

    /// Replace the `details` relationship list — AccessKit's analogue of
    /// `aria-details`.
    ///
    /// Distinct from `described_by`, and deliberately so: a *description* is text
    /// a screen reader appends when announcing the element, while *details* points
    /// at a structured node the user can navigate **into**. The W3C annotations
    /// pattern is built on that difference — an annotated run carries
    /// `aria-details` to a `role="comment"` node, so the reader can say "has
    /// comment" and let the user go read it, rather than reciting a whole thread
    /// inline every time the caret crosses the span.
    pub fn set_details(&mut self, ids: impl Into<Vec<NodeId>>) {
        self.inner.set_details(ids);
    }

    /// Append one node to the `details` relationship list.
    ///
    /// It is a list, not a single id, because overlapping annotations are normal:
    /// one run of text can carry several comments, and each gets its own entry.
    pub fn push_detail(&mut self, id: NodeId) {
        self.inner.push_detail(id);
    }

    /// Stable author-supplied identifier (test/debug id, equivalent to
    /// `aria-label`-style `data-testid`). Maps to `accesskit::Node::set_author_id`.
    pub fn set_author_id(&mut self, id: impl Into<String>) {
        self.inner.set_author_id(id.into());
    }

    /// Replace the node's custom-action list with `actions`, and keep the
    /// supported-action gate in step with it.
    ///
    /// **The gate is the whole reachability story, not the list.** A platform
    /// adapter reports a node's custom actions through
    /// [`accesskit::Action::CustomAction`] being
    /// supported, not through the list being non-empty
    /// (`accesskit_ios-0.2.0/src/node.rs:109` is the one that says so in code),
    /// so a list published without it is decoration: named, announced by
    /// nothing, invokable by nobody. Three separate widgets in this repo have
    /// shipped that exact defect, each having to remember a second call beside
    /// this one.
    ///
    /// So this method owns both halves. A non-empty list advertises the gate; an
    /// empty one withdraws it, because a gate with nothing behind it offers an
    /// assistive-technology user a menu that is not there. Callers that also
    /// call `add_action(Action::CustomAction)` themselves are correct and
    /// unaffected — both operations are idempotent.
    pub fn set_custom_actions(&mut self, actions: Vec<accesskit::CustomAction>) {
        let empty = actions.is_empty();
        self.inner.set_custom_actions(actions);
        if empty {
            self.remove_action(accesskit::Action::CustomAction);
        } else {
            self.add_action(accesskit::Action::CustomAction);
        }
    }

    pub fn set_toggled(&mut self, toggled: bool) {
        self.toggled = Some(toggled);
        self.inner.set_toggled(if toggled {
            accesskit::Toggled::True
        } else {
            accesskit::Toggled::False
        });
    }

    pub fn set_expanded(&mut self, expanded: bool) {
        self.expanded = Some(expanded);
        self.inner.set_expanded(expanded);
    }

    pub fn set_has_popup(&mut self, kind: accesskit::HasPopup) {
        self.inner.set_has_popup(kind);
    }

    /// Placeholder text displayed when the widget has no user-entered value
    /// yet. Screen readers treat this distinctly from `value` — they'll
    /// announce the placeholder as hint text rather than as the current
    /// value. Used by `ComboBox` when selection is `None`, by `TextInput`
    /// before the user types, etc.
    pub fn set_placeholder(&mut self, placeholder: impl Into<String>) {
        self.inner.set_placeholder(placeholder.into());
    }

    /// Target URL for link-like widgets. Maps to `aria-url` / platform
    /// link metadata so screen readers can announce the destination
    /// (e.g. "link, `https://example.com`"). Informational only — does
    /// not navigate when activated.
    pub fn set_url(&mut self, url: impl Into<String>) {
        self.inner.set_url(url.into());
    }

    /// Keyboard shortcut announcement (e.g. `"Ctrl+S"`). Maps to
    /// `aria-keyshortcuts`. Used by menu items and buttons whose
    /// chord is shown visually but must also be exposed to assistive
    /// tech so shortcut users discover it.
    pub fn set_keyboard_shortcut(&mut self, shortcut: impl Into<String>) {
        self.inner.set_keyboard_shortcut(shortcut.into());
    }

    /// Autocomplete behavior for combobox / text input widgets. Maps to
    /// ARIA `aria-autocomplete`: `Inline` completes within the field,
    /// `List` shows a popup of matching values, `Both` does both.
    pub fn set_auto_complete(&mut self, kind: accesskit::AutoComplete) {
        self.inner.set_auto_complete(kind);
    }

    /// Selection state — used by `RadioButton`, `Tab`, `ListBoxOption`,
    /// `TreeItem`, menu items in radio/check groups, etc. This is the
    /// correct property for "this option in a mutually exclusive
    /// group is the active one"; don't confuse with `set_toggled`,
    /// which models checkbox/switch on-off state.
    pub fn set_selected(&mut self, selected: bool) {
        self.selected = Some(selected);
        self.inner.set_selected(selected);
    }

    pub fn set_orientation(&mut self, orientation: accesskit::Orientation) {
        self.inner.set_orientation(orientation);
    }

    /// **1-based** index of this item in its parent set — the ARIA
    /// `aria-posinset` convention, so the first item is 1.
    ///
    /// Use on `Role::Tab`, `Role::ListBoxOption`, `Role::Row`,
    /// `Role::MenuItem` and similar collection items, and set
    /// [`set_size_of_set`](Self::set_size_of_set) on their **container** so
    /// assistive technology can announce "tab 3 of 5".
    ///
    /// ⚠ AccessKit's own `position_in_set` is **zero-based**, unlike
    /// `aria-posinset` — see `accesskit-0.25.0/src/lib.rs`, "Difference with
    /// ARIA". This wrapper converts, so callers keep the ARIA convention that
    /// every caller and every doc in this repository already assumed. Do not
    /// reach past it with `inner_mut().set_position_in_set(..)`: that skips the
    /// conversion, and the value then arrives one too high on Windows and
    /// Linux, both of which add the 1 back
    /// (`accesskit_windows-0.35.0/src/node.rs:682-687`,
    /// `accesskit_atspi_common-0.20.0/src/node.rs:394`).
    pub fn set_position_in_set(&mut self, position: usize) {
        self.inner
            .set_position_in_set(to_accesskit_ordinal(position));
    }

    /// Total number of items in a collection — maps to ARIA `aria-setsize`.
    ///
    /// ⚠ Set this on the **container** (`Role::ListBox`, `Role::TabList`,
    /// `Role::Tree`, `Role::Menu`, …), not on each item. Unlike
    /// `aria-setsize`, which is per item, AccessKit resolves an item's set size
    /// by walking *up* from its parent: `size_of_set_from_container`
    /// (`accesskit_consumer-0.39.0/src/node.rs:629-641`) starts at
    /// `filtered_parent`, so a value written on the item itself is read by no
    /// adapter on any platform.
    ///
    /// Report the **logical** set size, not the realized virtualization window:
    /// 200 for a 200-row list even when 20 rows exist as widgets.
    pub fn set_size_of_set(&mut self, size: usize) {
        self.inner.set_size_of_set(size);
    }

    /// **1-based** hierarchical depth — the ARIA `aria-level` convention, so a
    /// root tree item is level 1 and an `<h1>` is level 1.
    ///
    /// ⚠ AccessKit's `level` is **zero-based**, unlike `aria-level`. This
    /// wrapper converts. Reaching past it with `inner_mut().set_level(..)`
    /// makes every heading and every tree row announce one level too deep on
    /// Windows, which adds the 1 back
    /// (`accesskit_windows-0.35.0/src/node.rs:698-701`).
    pub fn set_level(&mut self, level: usize) {
        self.inner.set_level(to_accesskit_ordinal(level));
    }

    // ── Grid / table semantics (`aria-rowcount` / `aria-colindex` / …) ──
    //
    // Typed wrappers over the corresponding `accesskit::Node` setters so
    // grid/table widgets don't have to drop to `inner_mut()`. On a
    // `Role::Grid` / `Role::Table` container set the *logical* row/column
    // counts (not the realized window); on each cell set its 1-based
    // row/column index.

    /// Total logical row count on a grid/table container (`aria-rowcount`).
    pub fn set_row_count(&mut self, count: usize) {
        self.inner.set_row_count(count);
    }

    /// Total logical column count on a grid/table container (`aria-colcount`).
    pub fn set_column_count(&mut self, count: usize) {
        self.inner.set_column_count(count);
    }

    /// **1-based** row index of a cell or row — the ARIA `aria-rowindex`
    /// convention, so the header row is 1 and the first body row is 2.
    ///
    /// ⚠ AccessKit's `row_index` is **zero-based**, unlike `aria-rowindex`.
    /// This wrapper converts; `inner_mut().set_row_index(..)` does not.
    pub fn set_row_index(&mut self, index: usize) {
        self.inner.set_row_index(to_accesskit_ordinal(index));
    }

    /// **1-based** column index of a cell — the ARIA `aria-colindex`
    /// convention, so the leftmost column is 1.
    ///
    /// ⚠ AccessKit's `column_index` is **zero-based**, unlike `aria-colindex`.
    /// This wrapper converts; `inner_mut().set_column_index(..)` does not.
    pub fn set_column_index(&mut self, index: usize) {
        self.inner.set_column_index(to_accesskit_ordinal(index));
    }

    /// Number of rows a cell spans (`aria-rowspan`).
    pub fn set_row_span(&mut self, span: usize) {
        self.inner.set_row_span(span);
    }

    /// Number of columns a cell spans (`aria-colspan`).
    pub fn set_column_span(&mut self, span: usize) {
        self.inner.set_column_span(span);
    }

    /// Whether the container allows multiple selected items
    /// (`aria-multiselectable`). Set on the `Role::Grid` / `Role::ListBox`
    /// container in multi-select mode.
    pub fn set_multiselectable(&mut self, value: bool) {
        if value {
            self.inner.set_multiselectable();
        } else {
            self.inner.clear_multiselectable();
        }
    }

    /// The currently-active descendant (`aria-activedescendant`) — the
    /// roving-focus pattern where focus stays on a composite container and
    /// this points at the focused child (e.g. the focused grid cell).
    pub fn set_active_descendant(&mut self, id: NodeId) {
        self.inner.set_active_descendant(id);
    }

    /// Flag the node as a modal dialog. Use on `Role::Dialog` /
    /// `Role::AlertDialog` when input is blocked outside the dialog.
    pub fn set_modal(&mut self) {
        self.inner.set_modal();
    }

    /// Mark this node as the current item within its container
    /// (e.g. the "current page" crumb inside a `Navigation`, the
    /// current step in a wizard). Maps to ARIA `aria-current`.
    pub fn set_aria_current(&mut self, current: accesskit::AriaCurrent) {
        self.inner.set_aria_current(current);
    }

    /// Single-step delta for `Slider` / `SpinButton` — how much the
    /// value changes per keyboard arrow or Action::Increment tick.
    pub fn set_numeric_value_step(&mut self, step: f64) {
        self.inner.set_numeric_value_step(step);
    }

    /// Page-step delta for `Slider` / `SpinButton` — how much the
    /// value changes per PgUp/PgDown or coarse adjustment.
    pub fn set_numeric_value_jump(&mut self, jump: f64) {
        self.inner.set_numeric_value_jump(jump);
    }

    /// Append a controlled-node relationship — e.g. a `Tab` pointing
    /// at its matching `TabPanel`, a `ComboBox` pointing at its
    /// listbox popup. AccessKit / ARIA equivalent of `aria-controls`.
    pub fn push_controlled(&mut self, id: NodeId) {
        self.inner.push_controlled(id);
    }

    /// Declare this radio button's membership in a radio group.
    /// Each `RadioButton` node should push every sibling in its
    /// group (including itself); screen readers use this to
    /// announce positional info like "2 of 3".
    pub fn push_to_radio_group(&mut self, id: NodeId) {
        self.inner.push_to_radio_group(id);
    }

    pub fn set_numeric_value(&mut self, value: f64) {
        self.inner.set_numeric_value(value);
    }

    pub fn set_min_numeric_value(&mut self, value: f64) {
        self.inner.set_min_numeric_value(value);
    }

    pub fn set_max_numeric_value(&mut self, value: f64) {
        self.inner.set_max_numeric_value(value);
    }

    /// Hide this node **and everything under it** from all assistive
    /// technologies (equivalent to `aria-hidden="true"`). The node is still
    /// in the widget tree but is invisible to screen readers and other ATs.
    /// Use for purely decorative elements, e.g. scrollbars (AT scrolls via
    /// the parent `ScrollView`'s scroll actions instead).
    ///
    /// The flag covers the subtree. `accesskit_consumer`, which the AT-SPI,
    /// UIA and macOS adapters all read the tree through, reads a hidden node
    /// as `ExcludeSubtree` and treats a node as hidden when any ancestor is,
    /// so nothing below it reaches a screen reader except a node that holds
    /// focus, and that one is not listed among its parent's children. A
    /// wrapper that is only chrome around content a reader needs (a panel,
    /// a frame, a layout shell) must not call this: it is a
    /// `Role::GenericContainer` carrying nothing else, which the walker
    /// prunes and the adapters drop while keeping its children.
    pub fn set_hidden(&mut self) {
        self.hidden = true;
        self.inner.set_hidden();
    }

    /// Clear the hidden flag set by an earlier `set_hidden()` call on this
    /// node. Used by the override layer to re-expose a widget that hid
    /// itself. It clears this node's own flag only: a node under a hidden
    /// ancestor stays hidden, because the consumer the platform adapters
    /// read through inherits the flag from every ancestor.
    pub fn clear_hidden(&mut self) {
        self.hidden = false;
        self.inner.clear_hidden();
    }

    pub fn is_hidden(&self) -> bool {
        self.hidden
    }

    pub fn role(&self) -> Role {
        self.role
    }

    pub fn name(&self) -> Option<&str> {
        self.name.as_deref()
    }

    pub fn actions(&self) -> &[Action] {
        &self.actions
    }

    pub fn value(&self) -> Option<&str> {
        self.value.as_deref()
    }

    pub fn toggled(&self) -> Option<bool> {
        self.toggled
    }

    /// The node's numeric value (`Node::numeric_value`), as set by the widget
    /// or an `access_numeric_value` override.
    pub fn numeric_value(&self) -> Option<f64> {
        self.inner.numeric_value()
    }

    /// The node's numeric lower bound (`Node::min_numeric_value`).
    pub fn min_numeric_value(&self) -> Option<f64> {
        self.inner.min_numeric_value()
    }

    /// The node's numeric upper bound (`Node::max_numeric_value`).
    pub fn max_numeric_value(&self) -> Option<f64> {
        self.inner.max_numeric_value()
    }

    /// The node's custom actions, in declaration order (the widget's own
    /// first, then the application's `access_custom_action` entries).
    pub fn custom_actions(&self) -> &[accesskit::CustomAction] {
        self.inner.custom_actions()
    }

    pub fn expanded(&self) -> Option<bool> {
        self.expanded
    }

    pub fn selected(&self) -> Option<bool> {
        self.selected
    }

    /// Build the AccessKit Node with the given ID. Resolves any
    /// `pending_self_selection` recorded via `set_caret_position_on_self`
    /// or `set_text_selection_on_self` — at this point we know the
    /// widget's NodeId and can inject it into the text selection.
    /// Returns the primary `(NodeId, Node)` pair plus any synthetic
    /// child nodes emitted by the widget via `push_paragraph_child`
    /// / `push_text_run_child`. The tree walker is responsible for
    /// merging these into the final `TreeUpdate`.
    pub fn build(
        mut self,
        id: WidgetId,
    ) -> (
        NodeId,
        Node,
        Vec<(NodeId, Node)>,
        Vec<(NodeId, teksilo_canvas::Rect)>,
    ) {
        let node_id = widget_id_to_node_id(id);
        // Priority: explicit (child-targeting) selection wins over
        // self-targeting selection — widgets that emit TextRun
        // children use the explicit path.
        if let Some((anchor, focus)) = self.pending_explicit_selection.take() {
            let selection = TextSelection { anchor, focus };
            self.inner.set_text_selection(selection);
        } else if let Some((anchor, focus)) = self.pending_self_selection.take() {
            let selection = TextSelection {
                anchor: TextPosition {
                    node: node_id,
                    character_index: anchor,
                },
                focus: TextPosition {
                    node: node_id,
                    character_index: focus,
                },
            };
            self.inner.set_text_selection(selection);
        }

        // accesskit contract: a `Role::Label` node carries its text in the
        // `value` property, NOT `label`. Every platform adapter reads it that
        // way — Windows UIA derives the node's Name from `value` (its
        // `label_comes_from_value()` returns true for `Role::Label`), macOS
        // maps `Role::Label` to `NSAccessibilityStaticTextRole` whose content
        // is exposed as AXValue, and `accesskit_consumer` reads `value` when
        // another control is `labelled_by` this node. A name left in the
        // `label` property is therefore silently dropped on Windows and stray
        // on macOS. Widgets set the accessible name uniformly via `set_name`
        // (-> the `label` property); re-serialize it to `value` here, the one
        // place every emitted node is finalized — widget nodes (via the tree
        // walker) and scene synthetic children (via `push_scene_child`, which
        // also funnels through `build`). The builder's logical `name()` view
        // is intentionally left untouched, so introspection / `find_by_label`
        // continue to report the accessible name regardless of role. Reading
        // the inner node directly keeps this robust against any label set
        // outside `set_name`, and idempotent (a second pass finds no label).
        if self.inner.role() == Role::Label
            && let Some(label) = self.inner.label().map(|s| s.to_string())
        {
            if self.inner.value().is_none() {
                self.inner.set_value(label);
            }
            self.inner.clear_label();
        }

        // A role override away from a text-range-capable role leaves any
        // runs inert: no platform exposes them, and they would still cost
        // a node in every update and a child stop the walker has to
        // reconcile. Drop them rather than ship them.
        // `Role::Unknown` is exempt: it is the builder's initial value, so
        // dropping there would punish a caller that never set a role at all
        // rather than one that set a role text ranges cannot live under.
        // Such a node is pruned by the walker in any case.
        if !self.children_collected.is_empty()
            && self.inner.role() != Role::Unknown
            && !role_supports_text_ranges(self.inner.role())
            && let Some(run_ids) = own_run_ids(&self.inner, &self.children_collected)
        {
            self.children_collected
                .retain(|(cid, _)| !run_ids.contains(cid));
            self.child_local_bounds
                .retain(|(cid, _)| !run_ids.contains(cid));
            let kept: Vec<NodeId> = self
                .inner
                .children()
                .iter()
                .copied()
                .filter(|cid| !run_ids.contains(cid))
                .collect();
            self.inner.set_children(kept);
        }

        // Synthetic children declared in the widget's own space become
        // absolute here: the walker has already written the owner's
        // window-space rect onto `inner`, and this is the only point at
        // which both halves are in hand.
        let origin = self
            .inner
            .bounds()
            .map(|r| (r.x0, r.y0))
            .unwrap_or((0.0, 0.0));
        let local_bounds = std::mem::take(&mut self.child_local_bounds);
        for (child_id, local) in &local_bounds {
            let absolute = accesskit::Rect {
                x0: origin.0 + local.x as f64,
                y0: origin.1 + local.y as f64,
                x1: origin.0 + (local.x + local.width) as f64,
                y1: origin.1 + (local.y + local.height) as f64,
            };
            for (id, node) in self.children_collected.iter_mut() {
                if id == child_id {
                    node.set_bounds(absolute);
                    break;
                }
            }
        }

        (node_id, self.inner, self.children_collected, local_bounds)
    }

    /// Get a reference to the inner node for advanced use.
    pub fn inner_mut(&mut self) -> &mut Node {
        &mut self.inner
    }

    /// The widget id this builder was constructed for, if any. Set
    /// by [`AccessNodeBuilder::for_widget`]; used by the scene-tree
    /// walker to derive synthetic `NodeId`s for items / groups outside
    /// the closure form (`push_scene_child*`).
    pub fn owner_id(&self) -> Option<crate::widget_id::WidgetId> {
        self.owner
    }

    /// Run a mutator over a synthetic child node previously pushed
    /// via `push_scene_child` (or its `_under` variant). Used by
    /// the scene walker to apply cross-tree decorations (relations /
    /// live regions / landmarks) after the initial hierarchy emit.
    /// Returns `true` if the node was found.
    ///
    /// Cannot be used to mutate widget-derived NodeIds — those live
    /// in the global TreeUpdate and are owned by other widgets.
    pub fn with_collected_node<F: FnOnce(&mut Node)>(&mut self, node_id: NodeId, f: F) -> bool {
        for (id, node) in self.children_collected.iter_mut() {
            if *id == node_id {
                f(node);
                return true;
            }
        }
        false
    }

    /// Mark this node as read-only. Used by `RichTextEditor::read_only` so
    /// screen readers announce the widget as a document rather than a form
    /// field.
    pub fn set_read_only(&mut self) {
        self.inner.set_read_only();
    }

    /// Declare the current text selection. `anchor` and `focus` are
    /// character indices into the widget's flat text representation; pass
    /// equal indices for a collapsed caret. Uses the same `NodeId` for
    /// both positions (typical for single-node text widgets that expose
    /// the document as one run, which is what the first milestone of
    /// `RichTextEditor` does).
    pub fn set_text_selection(&mut self, node_id: NodeId, anchor: usize, focus: usize) {
        let selection = TextSelection {
            anchor: TextPosition {
                node: node_id,
                character_index: anchor,
            },
            focus: TextPosition {
                node: node_id,
                character_index: focus,
            },
        };
        self.inner.set_text_selection(selection);
    }

    /// Convenience for exposing a caret position as a collapsed selection.
    pub fn set_caret_position(&mut self, node_id: NodeId, character_index: usize) {
        self.set_text_selection(node_id, character_index, character_index);
    }

    /// Declare a text selection whose anchor and focus live on the
    /// widget's own AccessKit node. The widget doesn't know its own
    /// `NodeId` inside `accessibility(&self, builder)` — it's only
    /// resolved when the tree walker calls `builder.build(widget_id)`.
    /// This method stashes the character indices and defers the
    /// `set_text_selection` call until `build()` knows the ID.
    pub fn set_text_selection_on_self(&mut self, anchor: usize, focus: usize) {
        self.pending_self_selection = Some((anchor, focus));
    }

    /// Convenience wrapper for a collapsed caret on the widget's own node.
    pub fn set_caret_position_on_self(&mut self, character_index: usize) {
        self.set_text_selection_on_self(character_index, character_index);
    }

    // ── Sub-tree API: multi-node widgets (rich text, etc.) ─────────────

    /// Push a `Role::Paragraph` child on the current node and return
    /// its `NodeId`. The NodeId is synthetic (bit 63 set) and
    /// deterministic given the owning widget + `element_id`.
    ///
    /// The owning `WidgetId` comes from the builder's `owner`
    /// field, set by `AccessNodeBuilder::for_widget`. Returns
    /// `NodeId(0)` (a no-op placeholder) if the builder has no
    /// owner, which can only happen when a widget constructs a
    /// builder manually via `new()` instead of going through the
    /// tree walker. That's a programming error worth catching in
    /// debug.
    pub fn push_paragraph_child(&mut self, element_id: u64) -> NodeId {
        let Some(owner) = self.owner else {
            debug_assert!(
                false,
                "push_paragraph_child called on a builder with no owner — \
                 widgets must only call this from Widget::accessibility"
            );
            return NodeId(0);
        };
        let node_id = synthetic_node_id(owner, element_id, SyntheticKind::Paragraph);
        let node = Node::new(Role::Paragraph);
        self.children_collected.push((node_id, node));
        self.inner.push_child(node_id);
        node_id
    }

    /// Push a `Role::Comment` child carrying an annotation's text, and return its
    /// `NodeId` so the annotated run can point at it via [`Self::push_detail`].
    ///
    /// `group_id` must be the annotation's own durable identity (a comment's uid,
    /// never a store id), so the node keeps the same `NodeId` across rebuilds and
    /// a screen reader's cursor is not thrown out of the thread by an unrelated
    /// edit elsewhere in the document.
    ///
    /// Per the W3C annotations pattern the *body* carries the name; the annotated
    /// span itself must NOT be given an accessible name (`role="mark"` forbids it)
    /// — naming the span would make the reader announce the comment's text in
    /// place of the prose.
    pub fn push_annotation_child(&mut self, group_id: u64, text: impl Into<String>) -> NodeId {
        let Some(owner) = self.owner else {
            debug_assert!(
                false,
                "push_annotation_child called on a builder with no owner — \
                 widgets must only call this from Widget::accessibility"
            );
            return NodeId(0);
        };
        let node_id = synthetic_node_id(owner, group_id, SyntheticKind::Annotation);
        let mut node = Node::new(Role::Comment);
        node.set_value(text.into());
        self.children_collected.push((node_id, node));
        self.inner.push_child(node_id);
        node_id
    }

    /// Add a `details` target to an already-pushed **child** node.
    ///
    /// The sub-tree API builds children eagerly into `children_collected`, so a
    /// relation between two synthetic siblings (a `TextRun` and its annotation
    /// body) cannot go through the current node's own setters — it has to reach
    /// back into the collected child. A no-op if `child` was never pushed, which
    /// keeps a caller that emitted spans for a run it then skipped from panicking.
    pub fn push_detail_on_child(&mut self, child: NodeId, detail: NodeId) {
        if let Some((_, node)) = self
            .children_collected
            .iter_mut()
            .find(|(id, _)| *id == child)
        {
            node.push_detail(detail);
        }
    }

    /// Push a `Role::Link` child on the current node. Used by label
    /// widgets (e.g. `TextWidget` with `.markup(true)` enabled) to
    /// expose inline `[label](url)` links as individual accessible
    /// nodes alongside the parent's own text.
    ///
    /// `element_id` should be a stable identifier for the link inside
    /// the parent widget (typically the byte offset of the `[` in the
    /// original markup source, so the NodeId survives identical
    /// re-layouts).
    ///
    /// The returned `NodeId` is synthetic (bit 63 set) and deterministic
    /// given `(owner, element_id)`.
    pub fn push_link_child(
        &mut self,
        element_id: u64,
        label: impl Into<String>,
        url: impl Into<String>,
    ) -> NodeId {
        let Some(owner) = self.owner else {
            debug_assert!(
                false,
                "push_link_child called on a builder with no owner — \
                 widgets must only call this from Widget::accessibility"
            );
            return NodeId(0);
        };
        let node_id = synthetic_node_id(owner, element_id, SyntheticKind::Link);
        let mut node = Node::new(Role::Link);
        let label: String = label.into();
        if !label.is_empty() {
            node.set_label(label);
        }
        // AccessKit exposes the link target through the `Value` property
        // on a `Role::Link` node — same convention the standalone
        // `Link` widget uses via `set_value(...)`.
        node.set_value(url.into());
        self.children_collected.push((node_id, node));
        self.inner.push_child(node_id);
        node_id
    }

    /// Push a synthetic child node representing a lightweight
    /// `SceneItem` (or `SceneGroup`) emitted by `teksilo_scene::SceneView`.
    /// The caller customizes a sub-`AccessNodeBuilder` (mirroring the
    /// `Widget::accessibility` shape) and gets back the
    /// deterministic synthetic `NodeId` allocated for the
    /// `(owner, element_id, kind)` tuple.
    ///
    /// `kind` must be one of the synthetic kinds this path
    /// allocates: [`SyntheticKind::SceneItem`],
    /// [`SyntheticKind::SceneGroup`], [`SyntheticKind::SceneMagnet`],
    /// [`SyntheticKind::SceneHandle`], [`SyntheticKind::ChartMark`] or
    /// [`SyntheticKind::LaneMark`];
    /// passing any other variant panics in debug. The last two are
    /// how a chart or a margin lane emits one node per datum from
    /// its own `accessibility()`.
    ///
    /// Any further synthetic children the closure pushes (a
    /// `SceneGroup` containing nested `SceneItem`s) are forwarded into the parent's
    /// `children_collected` and re-parented under the
    /// just-pushed node via the closure's own `inner.push_child`
    /// calls — same convention as `push_paragraph_child` →
    /// `push_text_run_child`.
    pub fn push_scene_child(
        &mut self,
        element_id: u64,
        kind: SyntheticKind,
        customize: impl FnOnce(&mut AccessNodeBuilder),
    ) -> NodeId {
        debug_assert!(
            matches!(
                kind,
                SyntheticKind::SceneItem
                    | SyntheticKind::SceneGroup
                    | SyntheticKind::SceneMagnet
                    | SyntheticKind::SceneHandle
                    | SyntheticKind::ChartMark
                    | SyntheticKind::LaneMark
            ),
            "push_scene_child requires SyntheticKind::SceneItem, ::SceneGroup, ::SceneMagnet, ::SceneHandle, ::ChartMark, or ::LaneMark"
        );
        let Some(owner) = self.owner else {
            debug_assert!(
                false,
                "push_scene_child called on a builder with no owner — \
                 widgets must only call this from Widget::accessibility"
            );
            return NodeId(0);
        };
        let node_id = synthetic_node_id(owner, element_id, kind);
        // Build the child against a fresh sub-builder so the item
        // sees the same `&mut AccessNodeBuilder` shape as widgets.
        // Owner-id is the SceneView's so further `push_scene_child`
        // calls inside the customize closure (a `SceneGroup`
        // emitting nested items) hash off the same owner.
        let mut child_builder = AccessNodeBuilder::for_widget(owner);
        customize(&mut child_builder);
        // `build(owner)` re-derives a widget-keyed NodeId we throw
        // away — we use our synthetic `node_id` instead. The
        // returned `Node` carries the role / label / bounds / etc
        // the customize closure populated; any *grand*children the
        // closure pushed via further `push_scene_child` calls come
        // back in the third tuple field and we forward them so the
        // main TreeUpdate sees the full subtree.
        let (_unused, node, grand_children, _local) = child_builder.build(owner);
        self.children_collected.push((node_id, node));
        for (gid, gnode) in grand_children {
            self.children_collected.push((gid, gnode));
        }
        self.inner.push_child(node_id);
        node_id
    }

    /// Append an existing synthetic node id as a child of a
    /// previously-pushed `SceneGroup` (or `SceneItem`) child. Used by
    /// the scene logical-tree walker to re-parent items under their
    /// declared logical group rather than as direct children of the
    /// SceneView.
    ///
    /// Returns `true` if the parent was found (and the child was
    /// attached), `false` if the parent isn't in
    /// `children_collected` — the caller misordered the pushes.
    pub fn attach_scene_child_under(&mut self, parent: NodeId, child: NodeId) -> bool {
        for (id, node) in self.children_collected.iter_mut() {
            if *id == parent {
                node.push_child(child);
                return true;
            }
        }
        false
    }

    /// Like `push_scene_child` but lets the caller pick the
    /// parent. `parent = None` attaches to the widget's own node
    /// (same behavior as `push_scene_child`); `parent = Some(...)`
    /// attaches to the previously-pushed scene-child with that id.
    /// The scene logical-tree walker uses this to nest scene items
    /// under declared `A11yGroup` parents.
    ///
    /// Returns the deterministic synthetic `NodeId` for the new
    /// child. If `parent` was `Some` but the parent wasn't found
    /// in `children_collected`, the child still gets created and
    /// recorded but ends up attached to the widget's own node as a
    /// fallback (and a debug-assert fires).
    pub fn push_scene_child_under(
        &mut self,
        parent: Option<NodeId>,
        element_id: u64,
        kind: SyntheticKind,
        customize: impl FnOnce(&mut AccessNodeBuilder),
    ) -> NodeId {
        debug_assert!(
            matches!(
                kind,
                SyntheticKind::SceneItem
                    | SyntheticKind::SceneGroup
                    | SyntheticKind::SceneMagnet
                    | SyntheticKind::SceneHandle
                    | SyntheticKind::ChartMark
                    | SyntheticKind::LaneMark
            ),
            "push_scene_child_under requires SyntheticKind::SceneItem, ::SceneGroup, ::SceneMagnet, ::SceneHandle, ::ChartMark, or ::LaneMark"
        );
        let Some(owner) = self.owner else {
            debug_assert!(
                false,
                "push_scene_child_under called on a builder with no owner — \
                 widgets must only call this from Widget::accessibility"
            );
            return NodeId(0);
        };
        let node_id = synthetic_node_id(owner, element_id, kind);
        let mut child_builder = AccessNodeBuilder::for_widget(owner);
        customize(&mut child_builder);
        let (_unused, node, grand_children, _local) = child_builder.build(owner);
        self.children_collected.push((node_id, node));
        for (gid, gnode) in grand_children {
            self.children_collected.push((gid, gnode));
        }
        match parent {
            Some(parent_id) => {
                let attached = self.attach_scene_child_under(parent_id, node_id);
                if !attached {
                    debug_assert!(
                        false,
                        "push_scene_child_under: parent {:?} not in children_collected — \
                         caller must push the parent before its children",
                        parent_id
                    );
                    self.inner.push_child(node_id);
                }
            }
            None => {
                self.inner.push_child(node_id);
            }
        }
        node_id
    }

    /// Override a previously-pushed paragraph child's role to
    /// `Role::Heading` with the given hierarchical level. Used by
    /// the rich text editor when a block carries a
    /// `BlockFormat::heading_level`. Returns `true` if the node was
    /// found and updated, `false` otherwise (caller misused the
    /// api — the paragraph must have been pushed earlier).
    pub fn set_paragraph_as_heading(&mut self, node_id: NodeId, level: u8) -> bool {
        for (id, node) in self.children_collected.iter_mut() {
            if *id == node_id {
                node.set_role(Role::Heading);
                // AccessKit's `set_level` takes a usize (via the
                // usize_property_methods macro). Clamp to 1..=6 for
                // conventional heading semantics.
                // Clamped to the conventional 1..=6 heading range, then
                // converted: AccessKit's `level` is zero-based, so an H1 is 0.
                // Writing the 1-based number straight through made every
                // heading announce one level too deep on Windows, and made
                // "heading level 1" unreachable.
                let level: usize = to_accesskit_ordinal((level as usize).clamp(1, 6));
                node.set_level(level);
                return true;
            }
        }
        false
    }

    /// Set the **1-based** position-in-set on a previously-pushed synthetic
    /// child (a paragraph, "line 42 of 200"), and the set size on this widget's
    /// own node, which is the container the child hangs from.
    ///
    /// AccessKit exposes `position_in_set` on every node, but
    /// [`set_position_in_set`](Self::set_position_in_set) only touches the
    /// widget's own node. This reaches a collected child by NodeId, the same
    /// way [`set_paragraph_as_heading`](Self::set_paragraph_as_heading) does,
    /// and applies the same 1-based-to-zero-based conversion.
    ///
    /// `size` deliberately lands on the parent rather than the child: AccessKit
    /// resolves a set size by walking up from the item, so a size written on
    /// the child is read by nobody. See
    /// [`set_size_of_set`](Self::set_size_of_set).
    ///
    /// Returns whether the child was found.
    pub fn set_child_position_in_set(
        &mut self,
        node_id: NodeId,
        position: usize,
        size: usize,
    ) -> bool {
        let found = self.with_collected_node(node_id, |node| {
            node.set_position_in_set(to_accesskit_ordinal(position));
        });
        if found {
            self.inner.set_size_of_set(size);
        }
        found
    }

    /// Declare this node's base reading direction.
    ///
    /// AccessKit's text APIs read the direction from the *run*; the root
    /// carries it so a consumer that asks the container — and every
    /// platform that maps a paragraph direction onto its own attribute —
    /// gets an answer for an empty or geometry-less node too.
    pub fn set_text_direction(&mut self, direction: accesskit::TextDirection) {
        self.inner.set_text_direction(direction);
    }

    /// Set the reading direction of a synthetic child pushed earlier.
    /// Returns `true` if the child was found.
    pub fn set_child_text_direction(
        &mut self,
        child: NodeId,
        direction: accesskit::TextDirection,
    ) -> bool {
        self.with_collected_node(child, |node| node.set_text_direction(direction))
    }

    /// Declare a synthetic child's bounds in the **owner's own**
    /// coordinate space; [`build`](Self::build) translates them into
    /// window space once the owner's absolute rect is known.
    ///
    /// This is what a widget should use for geometry it derives from its
    /// own layout — a label's line boxes, an editor's rows. A widget
    /// holding rects that are *already* absolute (a scene item under a
    /// view transform) calls `set_bounds` on the child node instead and
    /// never comes through here.
    ///
    /// Returns `true` if the child was found.
    pub fn set_child_bounds_local(&mut self, child: NodeId, rect: teksilo_canvas::Rect) -> bool {
        if !self.children_collected.iter().any(|(id, _)| *id == child) {
            return false;
        }
        self.child_local_bounds.push((child, rect));
        true
    }

    /// Link a run of `Role::TextRun` children as one visual line, so assistive
    /// technology navigating by line treats them as a continuous line rather
    /// than fracturing at each formatting or chunk boundary.
    ///
    /// Sets each run's `next_on_line` to its successor and each successor's
    /// `previous_on_line` to its predecessor (AccessKit's doubly-linked
    /// same-line chain); the first run keeps no `previous_on_line` and the last
    /// no `next_on_line`, which is how the consumer detects the line's ends. A
    /// slice of zero or one is a no-op. Every id must be a run pushed earlier via
    /// [`push_text_run`](Self::push_text_run) — or the older
    /// [`push_text_run_child`](Self::push_text_run_child).
    pub fn link_runs_on_line(&mut self, run_ids: &[NodeId]) {
        for pair in run_ids.windows(2) {
            let (a, b) = (pair[0], pair[1]);
            self.with_collected_node(a, |node| node.set_next_on_line(b));
            self.with_collected_node(b, |node| node.set_previous_on_line(a));
        }
    }

    /// Attach an already-built synthetic child under `parent` (another
    /// collected child) or under the widget's own node.
    ///
    /// Returns `None` when `node_id` was already pushed: a duplicate child id
    /// panics `accesskit_consumer`'s tree builder, so it is dropped here with
    /// a diagnostic instead — the rule [`Self::push_text_run`] follows. The
    /// owner check belongs to the callers, which need it to derive `node_id`
    /// in the first place.
    fn push_collected_child(
        &mut self,
        parent: Option<NodeId>,
        node_id: NodeId,
        node: Node,
    ) -> Option<NodeId> {
        if self.children_collected.iter().any(|(id, _)| *id == node_id) {
            debug_assert!(
                false,
                "Teksilo bug: two accessibility children of widget {:?} derived \
                 the same node id {node_id:?}. Please file a bug report.",
                self.owner
            );
            // Paired with an `eprintln!` for the same reason `push_text_run`
            // has one: the `debug_assert!` compiles out, and a silent drop
            // here loses a whole subtree — a table row and every character in
            // it — with nothing to show for it in a shipped build.
            eprintln!(
                "Teksilo bug: two accessibility children of widget {:?} derived \
                 the same node id {node_id:?}; the second was dropped. Please \
                 file a bug report.",
                self.owner
            );
            return None;
        }
        self.children_collected.push((node_id, node));
        match parent {
            Some(parent_node) => {
                for (id, collected) in self.children_collected.iter_mut() {
                    if *id == parent_node {
                        collected.push_child(node_id);
                        return Some(node_id);
                    }
                }
                // Parent not found — attach to the widget's own node rather
                // than orphaning the child. Caller misused the API.
                self.inner.push_child(node_id);
            }
            None => self.inner.push_child(node_id),
        }
        Some(node_id)
    }

    /// Push a `Role::Table` child carrying its dimensions, under `parent`
    /// when given and under the widget's own node otherwise.
    ///
    /// `element_id` must be the document's own durable table id, so the node
    /// keeps its `NodeId` across edits and a screen reader's cursor is not
    /// thrown out of the table by an unrelated change elsewhere.
    pub fn push_table_child(
        &mut self,
        parent: Option<NodeId>,
        element_id: u64,
        rows: usize,
        columns: usize,
    ) -> Option<NodeId> {
        let owner = self.owner?;
        let node_id = synthetic_node_id(owner, element_id, SyntheticKind::RichTextTable);
        let mut node = Node::new(Role::Table);
        node.set_row_count(rows);
        node.set_column_count(columns);
        self.push_collected_child(parent, node_id, node)
    }

    /// Push a `Role::Row` child under a table pushed by
    /// [`Self::push_table_child`].
    ///
    /// **1-based** `row_index`, the ARIA `aria-rowindex` convention this
    /// builder's whole public surface uses — so the first row is 1, exactly as
    /// for [`Self::set_row_index`]. The conversion to the zero-based number
    /// AccessKit stores happens here, at the same boundary every other ordinal
    /// on this builder is converted at.
    pub fn push_table_row_child(
        &mut self,
        parent: NodeId,
        element_id: u64,
        row_index: usize,
    ) -> Option<NodeId> {
        let owner = self.owner?;
        let node_id = synthetic_node_id(owner, element_id, SyntheticKind::RichTextTableRow);
        let mut node = Node::new(Role::Row);
        node.set_row_index(to_accesskit_ordinal(row_index));
        self.push_collected_child(Some(parent), node_id, node)
    }

    /// Push a `Role::Cell` child under a row pushed by
    /// [`Self::push_table_row_child`].
    ///
    /// **1-based** `row_index` / `column_index` (see
    /// [`Self::push_table_row_child`]); the spans are plain counts and are
    /// written only when they exceed 1, so an ordinary cell carries no
    /// span properties at all.
    pub fn push_table_cell_child(
        &mut self,
        parent: NodeId,
        element_id: u64,
        row_index: usize,
        column_index: usize,
        row_span: usize,
        column_span: usize,
    ) -> Option<NodeId> {
        let owner = self.owner?;
        let node_id = synthetic_node_id(owner, element_id, SyntheticKind::RichTextTableCell);
        let mut node = Node::new(Role::Cell);
        node.set_row_index(to_accesskit_ordinal(row_index));
        node.set_column_index(to_accesskit_ordinal(column_index));
        if row_span > 1 {
            node.set_row_span(row_span);
        }
        if column_span > 1 {
            node.set_column_span(column_span);
        }
        self.push_collected_child(Some(parent), node_id, node)
    }

    /// Push the `Role::Label` text container inside a cell, and return it so
    /// the cell's text runs can be pushed under it.
    ///
    /// See [`SyntheticKind::RichTextCellText`] for why the runs may not hang
    /// off the `Role::Cell` directly.
    ///
    /// The container is deliberately given no value of its own: the text is
    /// carried by the runs beneath it, which is how every other text surface
    /// in the framework exposes its content, and duplicating it here would
    /// have a reader announce the cell twice.
    pub fn push_cell_text_child(&mut self, parent: NodeId, element_id: u64) -> Option<NodeId> {
        let owner = self.owner?;
        let node_id = synthetic_node_id(owner, element_id, SyntheticKind::RichTextCellText);
        let node = Node::new(Role::Label);
        self.push_collected_child(Some(parent), node_id, node)
    }

    /// Push the `Role::Label` text container inside a structural block-level
    /// node, and return it so that block's text runs can be pushed under it.
    ///
    /// See [`SyntheticKind::RichTextBlockText`]. A heading keeps its own
    /// `Role::Heading` node — it is how a reader jumps through a document —
    /// and a blockquote keeps its `Role::Blockquote`; this sits between either
    /// and the runs so the text changes beneath still reach the platform.
    ///
    /// `element_id` is the **block's** id, so a heading nested in a blockquote
    /// still produces exactly one container.
    pub fn push_block_text_child(&mut self, parent: NodeId, element_id: u64) -> Option<NodeId> {
        let owner = self.owner?;
        let node_id = synthetic_node_id(owner, element_id, SyntheticKind::RichTextBlockText);
        let node = Node::new(Role::Label);
        self.push_collected_child(Some(parent), node_id, node)
    }

    /// Push a `Role::Blockquote` child, under `parent` when given and under
    /// the widget's own node otherwise.
    ///
    /// `element_id` must be the document's own frame id, so the node keeps its
    /// `NodeId` across edits.
    pub fn push_blockquote_child(
        &mut self,
        parent: Option<NodeId>,
        element_id: u64,
    ) -> Option<NodeId> {
        let owner = self.owner?;
        let node_id = synthetic_node_id(owner, element_id, SyntheticKind::RichTextBlockquote);
        let node = Node::new(Role::Blockquote);
        self.push_collected_child(parent, node_id, node)
    }

    /// Push one `Role::TextRun` child, under `parent` when given and
    /// under the widget's own node otherwise.
    ///
    /// The single door every text run in the framework goes through.
    /// Returns `None` when the builder has no owner (so no id can be
    /// derived) or when the id it derived is already taken — a duplicate
    /// child id panics `accesskit_consumer`'s tree builder, so it is
    /// dropped here with a diagnostic instead.
    ///
    /// Prefer [`text_runs::push_text_runs`], which owns the chunking,
    /// the word segmentation, the hard-break rule and the line links;
    /// this is the primitive underneath it.
    pub fn push_text_run(&mut self, parent: Option<NodeId>, spec: TextRunSpec) -> Option<NodeId> {
        let owner = self.owner?;
        let node_id = synthetic_node_id(owner, spec.element_id, SyntheticKind::TextRun);
        if let Some((existing, _)) = self
            .children_collected
            .iter()
            .find(|(id, _)| *id == node_id)
        {
            debug_assert!(
                false,
                "Teksilo bug: two text runs of widget {owner:?} derived the same \
                 accessibility node id {existing:?}. Give each source its own \
                 `TextRunSource::id_seed`. Please file a bug report."
            );
            eprintln!(
                "Teksilo bug: two text runs of widget {owner:?} derived the same \
                 accessibility node id {existing:?}; the second was dropped. \
                 Please file a bug report."
            );
            return None;
        }

        let TextRunSpec {
            value,
            character_lengths,
            word_starts,
            character_positions,
            character_widths,
            bounds,
            bounds_are_absolute,
            text_direction,
            attrs,
            ..
        } = spec;

        debug_assert_eq!(
            character_lengths.iter().map(|n| *n as usize).sum::<usize>(),
            value.len(),
            "AccessKit requires the character lengths of a text run to sum to its value's byte length"
        );
        let mut node = Node::new(Role::TextRun);
        node.set_value(value);
        let expected = character_lengths.len();
        node.set_character_lengths(character_lengths);
        node.set_word_starts(word_starts);
        // All four or none: `Range::bounding_boxes()` throws away every box
        // it has already collected the moment one run is missing any of
        // them, so a half-populated run empties the geometry of every
        // range that touches it.
        if character_positions.len() == expected && character_widths.len() == expected {
            node.set_character_positions(character_positions);
            node.set_character_widths(character_widths);
        }
        node.set_text_direction(text_direction);
        if bounds_are_absolute {
            node.set_bounds(accesskit::Rect {
                x0: bounds.x as f64,
                y0: bounds.y as f64,
                x1: (bounds.x + bounds.width) as f64,
                y1: (bounds.y + bounds.height) as f64,
            });
        }
        apply_run_attrs(&mut node, attrs);

        self.children_collected.push((node_id, node));
        if !bounds_are_absolute {
            self.child_local_bounds.push((node_id, bounds));
        }

        match parent {
            Some(parent_node) => {
                for (id, node) in self.children_collected.iter_mut() {
                    if *id == parent_node {
                        node.push_child(node_id);
                        return Some(node_id);
                    }
                }
                // Parent not found — attach to the widget's own node
                // rather than orphaning the run. Caller misused the API.
                self.inner.push_child(node_id);
            }
            None => self.inner.push_child(node_id),
        }
        Some(node_id)
    }

    /// Push a `Role::TextRun` child under `parent_node` (usually a
    /// paragraph NodeId returned from `push_paragraph_child`, but
    /// may also be the widget's own node for inline editors).
    ///
    /// `element_id` is the stable id of the underlying text-document
    /// inline element; combined with `parent_widget` and a
    /// disambiguator it produces a synthetic NodeId that survives
    /// edits. `fragment_offset` is the block-relative character
    /// offset of this run — used as the disambiguator so two
    /// highlight-split sub-runs sharing one source element don't
    /// collide.
    ///
    /// `character_lengths` must be the UTF-8 byte length of each
    /// character in `value`, per AccessKit's contract. Optional
    /// `word_starts`, `character_positions`, and `character_widths`
    /// populate the corresponding AccessKit properties.
    ///
    /// Returns the allocated synthetic `NodeId` so the caller can
    /// reference it later when attaching a `TextSelection` via
    /// `set_text_selection_to`.
    #[allow(clippy::too_many_arguments)]
    pub fn push_text_run_child(
        &mut self,
        parent_node: NodeId,
        element_id: u64,
        fragment_offset: usize,
        value: String,
        character_lengths: Vec<u8>,
        word_starts: Option<Vec<u8>>,
        character_positions: Option<Vec<f32>>,
        character_widths: Option<Vec<f32>>,
        attrs: TextRunAttributes,
    ) -> NodeId {
        let Some(owner) = self.owner else {
            debug_assert!(
                false,
                "push_text_run_child called on a builder with no owner — \
                 widgets must only call this from Widget::accessibility"
            );
            return NodeId(0);
        };
        // Give sub-runs of one source element (a highlight split, or a run
        // chunked to stay under the AccessKit word-start cap) distinct NodeIds.
        // A plain `element_id ^ (fragment_offset << 32)` would XOR the offset
        // into the very bits `element_id` already uses to encode the owning
        // block, so a chunk at offset 255 in block A could alias a whole-line run
        // in a block whose id is `A ^ 255`. Hashing the offset across all 64 bits
        // removes that structure; `fragment_offset == 0` (the whole-run common
        // case) stays a no-op, so those NodeIds are unchanged.
        let mixed_element = if fragment_offset == 0 {
            element_id
        } else {
            fnv_mix_u64(element_id, fragment_offset as u64, 0)
        };
        let node_id = synthetic_node_id(owner, mixed_element, SyntheticKind::TextRun);
        let mut node = Node::new(Role::TextRun);
        node.set_value(value);
        node.set_character_lengths(character_lengths);
        if let Some(ws) = word_starts {
            node.set_word_starts(ws);
        }
        if let Some(pos) = character_positions {
            node.set_character_positions(pos);
        }
        if let Some(widths) = character_widths {
            node.set_character_widths(widths);
        }
        // Text attributes (WCAG 1.3.1 / EN 301 549 11.5.2.9). AccessKit has no
        // bold flag, so an explicit weight wins, else bold => 700.
        if let Some(w) = attrs.font_weight {
            node.set_font_weight(w as f32);
        } else if attrs.bold {
            node.set_font_weight(700.0);
        }
        if attrs.italic {
            node.set_italic();
        }
        if attrs.underline {
            node.set_underline(default_text_decoration());
        }
        if attrs.strikethrough {
            node.set_strikethrough(default_text_decoration());
        }
        self.children_collected.push((node_id, node));
        // Attach the text-run to its parent paragraph's child list.
        // The parent must already be in `children_collected`.
        for (id, parent) in self.children_collected.iter_mut() {
            if *id == parent_node {
                parent.push_child(node_id);
                return node_id;
            }
        }
        // Parent not found — push as a direct child of the widget's
        // own node as a fallback. Caller misused the API.
        self.inner.push_child(node_id);
        node_id
    }

    /// Push a single `Role::TextRun` child attached **directly** to the
    /// widget's own node (no intervening `Role::Paragraph`). This is the
    /// single-line text-input shape: `Role::TextInput` → one
    /// `Role::TextRun`.
    ///
    /// Required for screen-reader typing echo. accesskit_consumer's
    /// `supports_text_ranges()` returns `false` for a text input that
    /// only sets `character_lengths` on its *own* node — it needs a
    /// `Role::TextRun` child. Without it the macOS adapter never emits
    /// `AXSelectedTextChanged`, so VoiceOver reads the value once on
    /// focus but never echoes characters/words while typing. Emit this
    /// even when `value` / `character_lengths` are empty so
    /// `supports_text_ranges()` is already true before the first
    /// keystroke (the change-diff's *old* node must also support ranges
    /// for the notification to fire). Target the caret/selection at the
    /// returned `NodeId` via [`set_text_selection_to`](Self::set_text_selection_to).
    pub fn push_text_run_child_on_self(
        &mut self,
        element_id: u64,
        value: String,
        character_lengths: Vec<u8>,
        word_starts: Option<Vec<u8>>,
    ) -> NodeId {
        let Some(owner) = self.owner else {
            debug_assert!(
                false,
                "push_text_run_child_on_self called on a builder with no owner — \
                 widgets must only call this from Widget::accessibility"
            );
            return NodeId(0);
        };
        let node_id = synthetic_node_id(owner, element_id, SyntheticKind::TextRun);
        let mut node = Node::new(Role::TextRun);
        node.set_value(value);
        node.set_character_lengths(character_lengths);
        if let Some(ws) = word_starts {
            node.set_word_starts(ws);
        }
        self.children_collected.push((node_id, node));
        self.inner.push_child(node_id);
        node_id
    }

    /// Declare a text selection that references TextRun children
    /// previously emitted via `push_text_run_child`. Both the
    /// anchor and the focus are expressed as
    /// `(NodeId, character_index)` pairs where the character index
    /// is an index into the target TextRun's `character_lengths`
    /// (NOT a document-absolute offset — per AccessKit's contract).
    pub fn set_text_selection_to(&mut self, anchor: (NodeId, usize), focus: (NodeId, usize)) {
        self.pending_explicit_selection = Some((
            TextPosition {
                node: anchor.0,
                character_index: anchor.1,
            },
            TextPosition {
                node: focus.0,
                character_index: focus.1,
            },
        ));
    }
}

impl Default for AccessNodeBuilder {
    fn default() -> Self {
        Self::new()
    }
}

/// Convert a WidgetId to an AccessKit NodeId.
///
/// This is the id the tree gives the widget's node, and the one every update
/// [`crate::WidgetTree::sync_accessibility`] returns carries. A platform
/// adapter can hold another for the same node: one that left the tree a
/// reader sees and came back is handed a new id on its way out, see
/// [`crate::WidgetTree::deliver_accessibility`].
pub fn widget_id_to_node_id(id: WidgetId) -> NodeId {
    use slotmap::Key;
    let key_data = id.data();
    let raw = key_data.as_ffi();
    NodeId(raw)
}

/// Convert an AccessKit NodeId back to a WidgetId. Returns `None`
/// for synthetic NodeIds (widget-emitted child nodes like TextRuns);
/// callers that need to route an `ActionRequest` targeting a
/// synthetic NodeId must consult `WidgetTree::synthetic_parent_map`
/// to find the owning widget.
pub fn node_id_to_widget_id_maybe(node_id: NodeId) -> Option<WidgetId> {
    if is_synthetic(node_id) {
        return None;
    }
    use slotmap::KeyData;
    let key_data = KeyData::from_ffi(node_id.0);
    Some(key_data.into())
}

/// Legacy infallible converter kept for existing call sites that
/// never encounter synthetic NodeIds. New code should prefer
/// [`node_id_to_widget_id_maybe`]. Panics in debug for synthetic
/// ids to catch misrouted calls early.
pub fn node_id_to_widget_id(node_id: NodeId) -> WidgetId {
    debug_assert!(
        !is_synthetic(node_id),
        "node_id_to_widget_id called on synthetic NodeId — use node_id_to_widget_id_maybe"
    );
    use slotmap::KeyData;
    let key_data = KeyData::from_ffi(node_id.0);
    key_data.into()
}

/// The special root node ID for the accessibility tree.
pub fn root_node_id() -> NodeId {
    NodeId(0)
}

/// Query result for accessibility information about a widget.
#[derive(Debug)]
pub struct AccessibilityInfo {
    role: Role,
    name: Option<String>,
    actions: Vec<Action>,
    toggled: Option<bool>,
    expanded: Option<bool>,
    selected: Option<bool>,
    disabled: bool,
    hidden: bool,
    published: bool,
    value: Option<String>,
    numeric_value: Option<f64>,
    min_numeric_value: Option<f64>,
    max_numeric_value: Option<f64>,
    custom_actions: Vec<String>,
}

impl AccessibilityInfo {
    pub fn new(role: Role, name: Option<String>, actions: Vec<Action>) -> Self {
        Self {
            role,
            name,
            actions,
            toggled: None,
            expanded: None,
            selected: None,
            disabled: false,
            hidden: false,
            published: true,
            value: None,
            numeric_value: None,
            min_numeric_value: None,
            max_numeric_value: None,
            custom_actions: Vec::new(),
        }
    }

    pub fn with_value(mut self, value: impl Into<String>) -> Self {
        self.value = Some(value.into());
        self
    }

    pub fn with_numeric_value(mut self, value: f64) -> Self {
        self.numeric_value = Some(value);
        self
    }

    /// Set the numeric range; either bound may be absent.
    pub fn with_numeric_range(mut self, min: Option<f64>, max: Option<f64>) -> Self {
        self.min_numeric_value = min;
        self.max_numeric_value = max;
        self
    }

    /// Set the custom-action labels, in declaration order.
    pub fn with_custom_actions(mut self, labels: Vec<String>) -> Self {
        self.custom_actions = labels;
        self
    }

    pub fn with_toggled(mut self, toggled: bool) -> Self {
        self.toggled = Some(toggled);
        self
    }

    pub fn with_expanded(mut self, expanded: bool) -> Self {
        self.expanded = Some(expanded);
        self
    }

    pub fn with_selected(mut self, selected: bool) -> Self {
        self.selected = Some(selected);
        self
    }

    pub fn with_disabled(mut self, disabled: bool) -> Self {
        self.disabled = disabled;
        self
    }

    pub fn with_hidden(mut self, hidden: bool) -> Self {
        self.hidden = hidden;
        self
    }

    /// Record whether the node is in the published AT tree; see
    /// [`published`](Self::published). A node is published unless set
    /// otherwise.
    pub fn with_published(mut self, published: bool) -> Self {
        self.published = published;
        self
    }

    pub fn role(&self) -> Role {
        self.role
    }

    pub fn name(&self) -> Option<&str> {
        self.name.as_deref()
    }

    pub fn actions(&self) -> &[Action] {
        &self.actions
    }

    pub fn is_toggled(&self) -> bool {
        self.toggled.unwrap_or(false)
    }

    pub fn is_expanded(&self) -> bool {
        self.expanded.unwrap_or(false)
    }

    pub fn is_selected(&self) -> bool {
        self.selected.unwrap_or(false)
    }

    pub fn is_disabled(&self) -> bool {
        self.disabled
    }

    pub fn is_hidden(&self) -> bool {
        self.hidden
    }

    /// Whether assistive technology can reach this node: `false` for a
    /// dormant node (a hidden `Switcher` page, a `visible_when(false)`
    /// branch), one under an ancestor whose subtree is excluded or merged,
    /// and one marked [hidden](Self::is_hidden).
    ///
    /// The other getters describe what the widget would say; this says
    /// whether it is being heard. A test that reads names across a tree
    /// filters on it.
    pub fn published(&self) -> bool {
        self.published && !self.hidden
    }

    /// The node's value text (`Node::value`), if it has one.
    pub fn value(&self) -> Option<&str> {
        self.value.as_deref()
    }

    /// The node's numeric value (a slider's position, a spin box's number).
    pub fn numeric_value(&self) -> Option<f64> {
        self.numeric_value
    }

    /// The lower bound of the numeric range, if the node declares one.
    pub fn min_numeric_value(&self) -> Option<f64> {
        self.min_numeric_value
    }

    /// The upper bound of the numeric range, if the node declares one.
    pub fn max_numeric_value(&self) -> Option<f64> {
        self.max_numeric_value
    }

    /// The labels of the node's custom actions, in declaration order (the
    /// widget's own first, then any `access_custom_action` overrides).
    pub fn custom_actions(&self) -> &[String] {
        &self.custom_actions
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn fake_widget(id: u64) -> WidgetId {
        slotmap::KeyData::from_ffi(id).into()
    }

    #[test]
    fn widget_derived_node_id_has_bit_63_clear() {
        // A freshly-minted slotmap key (version 1, index 0) encodes
        // to a u64 with bit 63 clear. The top-bit namespace split
        // (synthetic NodeIds set bit 63, widget-derived NodeIds clear
        // it) only works if widget-derived NodeIds stay below bit 63.
        let wid = fake_widget(1);
        let nid = widget_id_to_node_id(wid);
        assert_eq!(
            nid.0 & SYNTHETIC_BIT,
            0,
            "widget NodeId must have bit 63 clear"
        );
        assert!(!is_synthetic(nid));
    }

    #[test]
    fn synthetic_node_id_has_bit_63_set() {
        let wid = fake_widget(42);
        let nid = synthetic_node_id(wid, 17, SyntheticKind::TextRun);
        assert_eq!(nid.0 & SYNTHETIC_BIT, SYNTHETIC_BIT);
        assert!(is_synthetic(nid));
    }

    #[test]
    fn link_runs_on_line_chains_runs_both_ways() {
        let mut b = AccessNodeBuilder::for_widget(fake_widget(1));
        let para = b.push_paragraph_child(1);
        let run = |b: &mut AccessNodeBuilder, off: usize| {
            b.push_text_run_child(
                para,
                10,
                off,
                "abc".to_string(),
                vec![1, 1, 1],
                None,
                None,
                None,
                TextRunAttributes::default(),
            )
        };
        let (r0, r1, r2) = (run(&mut b, 0), run(&mut b, 3), run(&mut b, 6));
        b.link_runs_on_line(&[r0, r1, r2]);

        let (_id, _n, children, _local) = b.build(fake_widget(1));
        let node = |id| {
            children
                .iter()
                .find(|(i, _)| *i == id)
                .map(|(_, n)| n)
                .unwrap()
        };
        // First run: forward only. Middle: both. Last: back only.
        assert_eq!(node(r0).previous_on_line(), None);
        assert_eq!(node(r0).next_on_line(), Some(r1));
        assert_eq!(node(r1).previous_on_line(), Some(r0));
        assert_eq!(node(r1).next_on_line(), Some(r2));
        assert_eq!(node(r2).previous_on_line(), Some(r1));
        assert_eq!(node(r2).next_on_line(), None);
    }

    /// A chunk at a non-zero offset in one element must not collide with a
    /// whole run in another element, even when the two element ids differ by
    /// exactly the low-byte XOR of the chunk offset — the aliasing the old
    /// `element_id ^ (offset << 32)` mix allowed.
    #[test]
    fn a_chunk_offset_does_not_alias_another_elements_run() {
        let mut b = AccessNodeBuilder::for_widget(fake_widget(1));
        let para = b.push_paragraph_child(1);
        // `synth_element_id` encodes the block id in bits 32-61.
        let elem_a: u64 = 0xABCD_u64 << 32;
        let elem_b: u64 = (0xABCD_u64 ^ 255) << 32;
        let run = |b: &mut AccessNodeBuilder, elem: u64, off: usize| {
            b.push_text_run_child(
                para,
                elem,
                off,
                "x".to_string(),
                vec![1],
                None,
                None,
                None,
                TextRunAttributes::default(),
            )
        };
        let a_chunk = run(&mut b, elem_a, 255); // offset-255 chunk in block A
        let b_whole = run(&mut b, elem_b, 0); // whole run in block B = A ^ 255
        assert_ne!(
            a_chunk, b_whole,
            "a chunk offset must not alias another block's run NodeId"
        );
    }

    #[test]
    fn set_child_position_in_set_numbers_a_paragraph() {
        let mut b = AccessNodeBuilder::for_widget(fake_widget(1));
        let para = b.push_paragraph_child(5);
        assert!(b.set_child_position_in_set(para, 42, 200));
        assert!(
            !b.set_child_position_in_set(NodeId(999), 1, 1),
            "an unknown child is not found"
        );

        let (_id, own, children, _local) = b.build(fake_widget(1));
        let p = children
            .iter()
            .find(|(i, _)| *i == para)
            .map(|(_, n)| n)
            .unwrap();
        // The caller says "line 42", the ARIA convention. AccessKit stores the
        // zero-based 41, and the Windows and AT-SPI adapters add the 1 back.
        assert_eq!(p.position_in_set(), Some(41));
        // The set size belongs on the container, which here is the widget's own
        // node: `size_of_set_from_container` walks up from the item's parent,
        // so a size written on the paragraph itself is read by no adapter.
        assert_eq!(p.size_of_set(), None);
        assert_eq!(own.size_of_set(), Some(200));
    }

    /// The whole point of the 1-based public surface: a caller writes the
    /// number a person would say, and AccessKit gets the number it expects.
    #[test]
    fn every_aria_ordinal_is_converted_at_the_boundary() {
        let mut b = AccessNodeBuilder::for_widget(fake_widget(1));
        b.set_position_in_set(1);
        b.set_row_index(1);
        b.set_column_index(1);
        b.set_level(1);
        let (_id, n, _children, _local) = b.build(fake_widget(1));
        assert_eq!(n.position_in_set(), Some(0), "the first item is index 0");
        assert_eq!(n.row_index(), Some(0), "the header row is row 0");
        assert_eq!(n.column_index(), Some(0), "the leftmost column is column 0");
        assert_eq!(n.level(), Some(0), "a root item is level 0");
    }

    /// A count has no base, so it must pass through untouched. Getting this
    /// wrong would turn "3 of 12" into "3 of 11".
    #[test]
    fn a_count_is_not_an_ordinal_and_is_not_converted() {
        let mut b = AccessNodeBuilder::for_widget(fake_widget(1));
        b.set_size_of_set(12);
        b.set_row_count(100);
        b.set_column_count(4);
        b.set_row_span(2);
        b.set_column_span(3);
        let (_id, n, _children, _local) = b.build(fake_widget(1));
        assert_eq!(n.size_of_set(), Some(12));
        assert_eq!(n.row_count(), Some(100));
        assert_eq!(n.column_count(), Some(4));
        assert_eq!(n.row_span(), Some(2));
        assert_eq!(n.column_span(), Some(3));
    }

    /// A heading level is the same ARIA convention, and an H1 must be able to
    /// announce as level 1. Before the conversion the clamp floor of 1 made
    /// AccessKit level 0 unreachable, so no heading anywhere could.
    #[test]
    fn an_h1_is_accesskit_level_zero() {
        for (heading, expected) in [(1u8, 0usize), (2, 1), (6, 5)] {
            let mut b = AccessNodeBuilder::for_widget(fake_widget(1));
            let para = b.push_paragraph_child(7);
            assert!(b.set_paragraph_as_heading(para, heading));
            let (_id, _n, children, _local) = b.build(fake_widget(1));
            let p = children
                .iter()
                .find(|(i, _)| *i == para)
                .map(|(_, n)| n)
                .unwrap();
            assert_eq!(p.role(), Role::Heading);
            assert_eq!(p.level(), Some(expected), "h{heading}");
        }
    }

    #[test]
    fn synthetic_node_id_stable_across_calls() {
        // Same (widget, element, kind) produces identical NodeIds —
        // this stability is required for screen-reader focus to survive
        // accessibility rebuilds.
        let wid = fake_widget(42);
        let a = synthetic_node_id(wid, 17, SyntheticKind::TextRun);
        let b = synthetic_node_id(wid, 17, SyntheticKind::TextRun);
        assert_eq!(a, b);
    }

    #[test]
    fn synthetic_node_id_differs_by_kind() {
        let wid = fake_widget(42);
        let p = synthetic_node_id(wid, 17, SyntheticKind::Paragraph);
        let r = synthetic_node_id(wid, 17, SyntheticKind::TextRun);
        assert_ne!(
            p, r,
            "paragraph and text-run kinds must produce distinct NodeIds"
        );
    }

    #[test]
    fn synthetic_node_id_differs_by_element() {
        let wid = fake_widget(42);
        let a = synthetic_node_id(wid, 1, SyntheticKind::TextRun);
        let b = synthetic_node_id(wid, 2, SyntheticKind::TextRun);
        assert_ne!(a, b);
    }

    #[test]
    fn node_id_to_widget_id_maybe_returns_none_for_synthetic() {
        let wid = fake_widget(42);
        let syn = synthetic_node_id(wid, 17, SyntheticKind::TextRun);
        assert!(node_id_to_widget_id_maybe(syn).is_none());
    }

    #[test]
    fn node_id_to_widget_id_maybe_round_trips_widget_ids() {
        let wid = fake_widget(99);
        let nid = widget_id_to_node_id(wid);
        let back = node_id_to_widget_id_maybe(nid).unwrap();
        assert_eq!(wid, back);
    }

    #[test]
    fn push_paragraph_child_and_text_run_child_emit_synthetic_nodes() {
        let owner = fake_widget(7);
        let mut builder = AccessNodeBuilder::for_widget(owner);
        builder.set_role(Role::MultilineTextInput);

        let para = builder.push_paragraph_child(100);
        let run = builder.push_text_run_child(
            para,
            200,
            0,
            "hello".to_string(),
            vec![1, 1, 1, 1, 1],
            Some(vec![0]),
            None,
            None,
            TextRunAttributes::default(),
        );
        assert!(is_synthetic(para));
        assert!(is_synthetic(run));

        let (_nid, _node, children, _local) = builder.build(owner);
        // Two emitted children: paragraph + text run.
        assert_eq!(children.len(), 2);
        assert!(children.iter().any(|(id, _)| *id == para));
        assert!(children.iter().any(|(id, _)| *id == run));
    }

    #[test]
    fn text_run_attributes_reach_at_node() {
        // Audit G7 / EN 301 549 11.5.2.9: bold / italic / underline /
        // strikethrough formatting on a run is exposed on its TextRun node.
        let owner = fake_widget(9);
        let mut builder = AccessNodeBuilder::for_widget(owner);
        builder.set_role(Role::MultilineTextInput);
        let para = builder.push_paragraph_child(1);
        let run = builder.push_text_run_child(
            para,
            2,
            0,
            "ab".to_string(),
            vec![1, 1],
            None,
            None,
            None,
            TextRunAttributes {
                bold: true,
                italic: true,
                underline: true,
                strikethrough: true,
                ..Default::default()
            },
        );
        let (_nid, _node, children, _local) = builder.build(owner);
        let (_, run_node) = children
            .iter()
            .find(|(id, _)| *id == run)
            .expect("run node");
        assert_eq!(
            run_node.font_weight(),
            Some(700.0),
            "bold folds to font weight 700"
        );
        assert!(run_node.is_italic(), "italic flag set");
        assert!(run_node.underline().is_some(), "underline decoration set");
        assert!(
            run_node.strikethrough().is_some(),
            "strikethrough decoration set"
        );

        // An explicit numeric weight wins over the bold flag.
        let owner2 = fake_widget(10);
        let mut b2 = AccessNodeBuilder::for_widget(owner2);
        b2.set_role(Role::MultilineTextInput);
        let p2 = b2.push_paragraph_child(1);
        let r2 = b2.push_text_run_child(
            p2,
            2,
            0,
            "x".to_string(),
            vec![1],
            None,
            None,
            None,
            TextRunAttributes {
                bold: true,
                font_weight: Some(300),
                ..Default::default()
            },
        );
        let (_, _, kids2, _local) = b2.build(owner2);
        let (_, r2n) = kids2.iter().find(|(id, _)| *id == r2).expect("run2 node");
        assert_eq!(
            r2n.font_weight(),
            Some(300.0),
            "explicit weight wins over bold"
        );
    }

    #[test]
    fn set_text_selection_to_wins_over_self_selection() {
        let owner = fake_widget(3);
        let mut builder = AccessNodeBuilder::for_widget(owner);
        builder.set_role(Role::MultilineTextInput);
        // Emit a paragraph + run so set_text_selection_to has a
        // real synthetic NodeId to target.
        let para = builder.push_paragraph_child(1);
        let run = builder.push_text_run_child(
            para,
            2,
            0,
            "ab".to_string(),
            vec![1, 1],
            None,
            None,
            None,
            TextRunAttributes::default(),
        );
        // Both a self-targeted AND an explicit selection are
        // staged — the explicit one must win.
        builder.set_text_selection_on_self(0, 0);
        builder.set_text_selection_to((run, 0), (run, 2));
        let (_nid, node, _children, _local) = builder.build(owner);
        let sel = node.text_selection().expect("text selection set");
        assert_eq!(sel.focus.node, run);
        assert_eq!(sel.focus.character_index, 2);
    }

    /// A `Status` holding its text only as a value has no name on any
    /// platform, so it announces nothing: the adapters read a value as the
    /// name for a `Role::Label` alone.
    #[test]
    fn a_status_holding_its_text_as_a_value_announces_no_name() {
        let mut status = Node::new(Role::Status);
        status.set_value("Enregistré".to_string());
        assert_eq!(announced_text(&status), None);

        status.set_label("Prêt".to_string());
        assert_eq!(announced_text(&status), Some("Prêt"));
    }

    /// A `Role::Label` is named by its value, and by nothing else.
    #[test]
    fn a_label_is_named_by_its_value_alone() {
        let mut label = Node::new(Role::Label);
        label.set_label("Titre".to_string());
        assert_eq!(announced_text(&label), None);

        label.set_value("Enregistré".to_string());
        assert_eq!(announced_text(&label), Some("Enregistré"));
    }
}