teksilo_core/

widget_builder.rs

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

//! WidgetBuilder trait — blanket-implemented for all Widget types.
//!
//! Provides attached event handler methods and framework-level properties.
//! Each method wraps the widget in a `WidgetWithHandlers<W>` that stores
//! the handlers and metadata alongside the widget. When the widget is
//! inserted into the arena, the handler set is extracted and applied to
//! the `WidgetNode`.
//!
//! The four click-style handlers (`on_tap` / `on_double_tap` /
//! `on_triple_tap` / `on_long_press`) all receive a borrowed
//! [`crate::gesture::TapEvent`] (position + button + modifiers) and
//! default to [`crate::event::ButtonMask::PRIMARY`] acceptance. Widen
//! that filter via the matching `accept_*_buttons(...)` knob — see the
//! "Event System" section in `docs/events-and-gestures.md` for the
//! full contract and examples.

use teksilo_canvas::Point;

use crate::event::{ButtonMask, EventResponse, WidgetEvent};
use crate::event_handlers::EventHandlers;
use crate::gesture::MultiContact;
use crate::gesture::{DragPhase, PinchPhase, SwipeDirection, TapEvent};
use crate::pointer::touch_action::{PanAxes, PanClaim, TouchAction};
use crate::signal::Prop;
use crate::widget::{CursorIcon, EventContext, Widget};
use crate::widget_id::WidgetId;

// ---------------------------------------------------------------------------
// Accessibility overrides
// ---------------------------------------------------------------------------

/// Subtree visibility / merge mode applied by the accessibility tree walker.
///
/// Set via `WidgetBuilder::access_exclude_subtree()` /
/// `access_merge_subtree()`. The walker honors the mode after the parent
/// node has been emitted, before recursing into descendants.
#[derive(Default, Clone, Copy, PartialEq, Eq, Debug)]
pub enum AccessSubtreeMode {
    /// Normal walk — descendants emitted as their own AT nodes.
    #[default]
    Inherit,
    /// Descendants pruned from the AT tree entirely. Parent node still
    /// emitted normally. Equivalent to Flutter's `excludeSemantics: true`.
    Exclude,
    /// Descendants' labels / descriptions / values / actions are
    /// concatenated into the parent's emitted node, then descendants are
    /// pruned. The parent reads as a single AT element. Equivalent to
    /// Flutter's `mergeAllDescendants: true` and SwiftUI's
    /// `.accessibilityElement(children: .combine)`.
    Merge,
}

/// Builder-level accessibility overrides.
///
/// Carried on `HandlerSet` during builder-chain construction, mirrored
/// onto `WidgetNode::access_overrides` at arena insertion (parallel to
/// `clips_children` / `cursor` / `focus_within_signal`), then applied by
/// the accessibility tree walker after the inner widget's
/// `accessibility(&self, builder)` runs.
///
/// User-visible string fields store a `Prop<String>` rather than a
/// resolved `String`, so they stay reactive to locale changes.
/// `teksilo-core` can't name `LocalizedString` (that lives in the
/// downstream `teksilo-i18n` crate), but `Prop<String>` is a core type
/// and `impl From<LocalizedString> for Prop<String>` in `teksilo-i18n`
/// yields a `Prop::Bound` over a locale-observing `Signal<String>`. So
/// `.access_label(tr!(save()))` stores a bound prop; the accessibility
/// walker reads `.get()` at AT-build time, and `sync_accessibility`
/// re-walks on locale change so the announced value follows the locale.
/// The `_literal` builder variants store `Prop::Static` and are the
/// `#[doc(hidden)]` grep markers for explicitly untranslated call sites
/// (the only literal path reachable from within `teksilo-core`).
#[derive(Default)]
pub struct AccessibilityOverrides {
    // -- Tier 1: labeling / state -----------------------------------------
    pub label: Option<Prop<String>>,
    pub description: Option<Prop<String>>,
    pub value: Option<Prop<String>>,
    pub role: Option<accesskit::Role>,
    /// Reactive hidden-from-AT flag. `Some(prop)` where the prop reads
    /// `true` hides the node and its whole subtree from assistive
    /// technologies; `false` un-sets a
    /// hidden state the inner widget emitted unconditionally. Bound props are
    /// registered at `AccessibilityOnly` so the AT tree re-walks when they
    /// flip (see the insertion paths in `widget_tree.rs`).
    pub hidden: Option<Prop<bool>>,
    pub disabled: Option<bool>,

    // -- Tier 2: relationships / live / identity --------------------------
    pub identifier: Option<String>,
    pub controls: Vec<WidgetId>,
    pub described_by: Vec<WidgetId>,
    pub labelled_by: Vec<WidgetId>,
    pub live: Option<accesskit::Live>,
    pub aria_current: Option<accesskit::AriaCurrent>,
    /// Pre-formatted shortcut announcement string (e.g. `"Ctrl+S"`).
    /// Used by `access_shortcut_literal`. For chords routed through a
    /// `Shortcut` registration, prefer `access_shortcut_id` (stored
    /// in `shortcut_id`) so the announcement tracks rebinds.
    pub shortcut: Option<String>,
    /// Registered shortcut id (e.g. `"app.save"`). The accessibility
    /// walker resolves the current keystroke from
    /// `WidgetTree::shortcut_registry()` at AT-build time and writes
    /// the formatted string to `Node::keyboard_shortcut`. Refreshes
    /// automatically when the user rebinds (the registry's `version`
    /// signal triggers a re-sync).
    pub shortcut_id: Option<String>,
    pub has_popup: Option<accesskit::HasPopup>,
    pub orientation: Option<accesskit::Orientation>,

    // -- Tier 3: numeric / actions / escape hatch -------------------------
    pub numeric_value: Option<f64>,
    pub min_numeric_value: Option<f64>,
    pub max_numeric_value: Option<f64>,
    pub numeric_step: Option<f64>,

    /// Standard `accesskit::Action` advertisements with their handlers.
    /// Dispatched by `pointer_router.rs` when handling
    /// `WidgetEvent::AccessAction`, layered on top of any
    /// user-installed `on_access_action` / `on_access_action_request`
    /// handlers (both fire for the same dispatched event).
    pub actions: Vec<(accesskit::Action, Box<dyn FnMut(&mut EventContext)>)>,

    /// Actions to remove from the widget-emitted action list (called
    /// after the widget's `accessibility()` runs, before custom-action
    /// emission).
    pub removed_actions: Vec<accesskit::Action>,

    /// Custom-named actions (SwiftUI `.accessibilityAction(named:_:)`).
    /// Each entry pairs a (reactive) description prop with a handler.
    /// Index in the vec is the stable `i32` `CustomAction::id` exposed
    /// to AT software.
    pub custom_actions: Vec<(Prop<String>, Box<dyn FnMut(&mut EventContext)>)>,

    /// Final escape hatch — invoked **last** in `apply()` with full
    /// `&mut AccessNodeBuilder` access (including `inner_mut()`). Used
    /// for sub-node surgery (synthetic children) and for cases the
    /// typed surface doesn't cover.
    pub customize: Option<Box<dyn Fn(&mut crate::accessibility::AccessNodeBuilder)>>,
}

impl AccessibilityOverrides {
    /// Fold `other` into `self`: later scalars win, lists append.
    ///
    /// Needed because overrides reach a node from **two** directions — a builder
    /// chain at construction (`WidgetWithHandlers::access_*`) and a later
    /// [`BuildContext::apply_handlers`](crate::build_context::BuildContext::apply_handlers)
    /// on the same id, which is how a widget gives a node it already built one
    /// more action. Assigning the second block over the first silently dropped
    /// everything in the first, and nothing else reads an override block, so the
    /// loss was invisible: a `TreeTableView` row lost `ScrollIntoView` and its
    /// `Expand` / `Collapse` pair the moment it also gained a move command.
    ///
    /// The merge rules are the ones
    /// [the overrides page](https://github.com/ferntech-eu/teksilo/blob/main/docs/accessibility-overrides.md)
    /// already documents for a single block: scalars replace when set, lists
    /// append. `customize` is the exception — it is an escape hatch and both
    /// halves may matter, so two are **chained** in application order rather
    /// than one winning.
    pub(crate) fn merge_from(&mut self, other: Self) {
        macro_rules! scalar {
            ($($field:ident),+ $(,)?) => {
                $(if other.$field.is_some() { self.$field = other.$field; })+
            };
        }
        scalar!(
            label,
            description,
            value,
            role,
            hidden,
            disabled,
            identifier,
            live,
            aria_current,
            shortcut,
            shortcut_id,
            has_popup,
            orientation,
            numeric_value,
            min_numeric_value,
            max_numeric_value,
            numeric_step,
        );
        self.controls.extend(other.controls);
        self.described_by.extend(other.described_by);
        self.labelled_by.extend(other.labelled_by);
        self.actions.extend(other.actions);
        self.removed_actions.extend(other.removed_actions);
        // Appended, so the ids already published for the existing entries keep
        // pointing at the same handlers.
        self.custom_actions.extend(other.custom_actions);
        self.customize = match (self.customize.take(), other.customize) {
            (Some(first), Some(second)) => Some(Box::new(move |builder| {
                first(builder);
                second(builder);
            })),
            (first, second) => second.or(first),
        };
    }
}

impl std::fmt::Debug for AccessibilityOverrides {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("AccessibilityOverrides")
            .field("label", &self.label)
            .field("description", &self.description)
            .field("value", &self.value)
            .field("role", &self.role)
            .field("hidden", &self.hidden)
            .field("disabled", &self.disabled)
            .field("identifier", &self.identifier)
            .field("shortcut", &self.shortcut)
            .field("shortcut_id", &self.shortcut_id)
            .field("controls_len", &self.controls.len())
            .field("described_by_len", &self.described_by.len())
            .field("labelled_by_len", &self.labelled_by.len())
            .field("actions_len", &self.actions.len())
            .field("removed_actions", &self.removed_actions)
            .field("custom_actions_len", &self.custom_actions.len())
            .finish()
    }
}

impl AccessibilityOverrides {
    /// Apply the override scalar / list fields onto a builder. Called by
    /// the accessibility tree walker after the inner widget's
    /// `accessibility(&self, builder)` runs and before the framework
    /// finalizes the node.
    pub(crate) fn apply(&self, b: &mut crate::accessibility::AccessNodeBuilder) {
        use crate::accessibility::widget_id_to_node_id;

        if let Some(ref p) = self.label {
            b.set_name(p.get());
        }
        if let Some(ref p) = self.description {
            b.set_description(p.get());
        }
        if let Some(ref p) = self.value {
            b.set_value(p.get());
        }
        if let Some(role) = self.role {
            b.set_role(role);
        }
        match self.hidden.as_ref().map(|p| p.get()) {
            Some(true) => b.set_hidden(),
            Some(false) => b.clear_hidden(),
            None => {}
        }
        match self.disabled {
            Some(true) => b.set_disabled(),
            Some(false) => b.clear_disabled(),
            None => {}
        }
        if let Some(ref s) = self.identifier {
            b.set_author_id(s.clone());
        }
        for &id in &self.controls {
            b.push_controlled(widget_id_to_node_id(id));
        }
        for &id in &self.described_by {
            b.push_described_by(widget_id_to_node_id(id));
        }
        for &id in &self.labelled_by {
            b.push_labelled_by(widget_id_to_node_id(id));
        }
        if let Some(live) = self.live {
            b.set_live(live);
        }
        if let Some(c) = self.aria_current {
            b.set_aria_current(c);
        }
        if let Some(ref s) = self.shortcut {
            b.set_keyboard_shortcut(s.clone());
        }
        // `shortcut_id` resolution happens in the accessibility tree
        // walker (where the `ShortcutRegistry` is reachable) — see
        // `accessibility_emit_impl::build_accessibility_recursive`.
        if let Some(p) = self.has_popup {
            b.set_has_popup(p);
        }
        if let Some(o) = self.orientation {
            b.set_orientation(o);
        }
        if let Some(v) = self.numeric_value {
            b.set_numeric_value(v);
        }
        if let Some(v) = self.min_numeric_value {
            b.set_min_numeric_value(v);
        }
        if let Some(v) = self.max_numeric_value {
            b.set_max_numeric_value(v);
        }
        if let Some(v) = self.numeric_step {
            b.set_numeric_value_step(v);
        }
        // Suppression first, then advertisement — so `access_remove_action`
        // can prune what the widget emitted, but a subsequent
        // `access_action(same_action, ...)` re-advertises with the
        // override-installed handler.
        for &a in &self.removed_actions {
            b.remove_action(a);
        }
        for (action, _) in &self.actions {
            b.add_action(*action);
        }
        if !self.custom_actions.is_empty() {
            // Appended after the widget's own, which is the list rule every
            // other override list follows: replacing it took a slider's "Reset
            // to default" away the moment an application added an action of
            // its own. The override entries keep their positional ids, which is
            // what the dispatcher routes them by, so a widget publishing
            // actions of its own numbers them clear of the low ones.
            let mut custom: Vec<accesskit::CustomAction> = b.inner_mut().custom_actions().to_vec();
            custom.extend(
                self.custom_actions
                    .iter()
                    .enumerate()
                    .map(|(i, (label, _))| accesskit::CustomAction {
                        id: i as i32,
                        description: label.get(),
                    }),
            );
            b.set_custom_actions(custom);
            // A node's custom actions are only reachable when it also
            // advertises `Action::CustomAction`: an adapter reports the list
            // through the supported-action gate, not through the list's
            // emptiness (`accesskit_ios-0.2.0/src/node.rs:109` is the one that
            // says so in code). Without this the whole vector is decoration.
            b.add_action(accesskit::Action::CustomAction);
        }
        if let Some(ref f) = self.customize {
            f(b);
        }
    }
}

// ---------------------------------------------------------------------------
// HandlerSet — temporary storage before arena insertion
// ---------------------------------------------------------------------------

/// Type alias for a context-menu content factory.
///
/// The factory is invoked on every right-click that lands on a widget
/// owning the factory (or on a descendant whose nearest ancestor with
/// a factory is this one). It receives:
///
/// - `position`: pointer position in **window** coordinates — the factory
///   runs straight off the right-click `PointerDown`, before the localizing
///   handler dispatch, and the same point reaches every factory the walk
///   tries, so subtract the widget's own origin before hit-testing. Useful
///   when the menu's contents depend on *what* was right-clicked (a row in a
///   list, a node in a tree, an item under a hit-test, …).
/// - `ctx`: a full [`EventContext`], so the factory can read window
///   state, query app state, send intents (e.g. for analytics), or
///   update Signals before the menu mounts.
///
/// The same factory also answers the keyboard
/// ([`ContextMenuTrigger::Keyboard`]) and an assistive technology's
/// `ShowContextMenu` action. Neither carries a point, so `position` is then an
/// anchor the framework picked on the widget the menu is about, not a place
/// the user chose. [`ctx.context_menu_trigger()`](EventContext::context_menu_trigger)
/// says which it is: act on the point (move a caret to it, pick the item under
/// it) only for [`ContextMenuTrigger::Pointer`].
///
/// The factory returns:
///
/// - `Some(widget)` to mount `widget` as the menu overlay anchored at
///   the factory-owning widget, placed at `position`.
/// - `None` to **decline this right-click**. The framework continues
///   walking up the parent chain looking for the next ancestor with a
///   factory. This lets a widget conditionally suppress its own menu
///   without uninstalling the factory.
pub type ContextMenuFactory = Box<dyn Fn(Point, &mut EventContext) -> Option<Box<dyn Widget>>>;

/// What asked for a context menu, as a [`ContextMenuFactory`] reads it from
/// [`EventContext::context_menu_trigger`].
///
/// A factory is handed a point whatever opened the menu, and only a
/// pointer's point is one the user chose. For the keyboard and for assistive
/// technology the point is where the menu is drawn: a factory that treated it
/// as a click moved the caret of a text field to the middle of the field, and
/// the menu's Paste then wrote where the user had never been.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ContextMenuTrigger {
    /// A secondary click, or a hold with a finger or a pen: the point is
    /// where the user pointed.
    Pointer,
    /// The Menu key, Shift+F10, or on macOS Ctrl+Shift+M, on the focused
    /// widget.
    Keyboard,
    /// An assistive technology's
    /// [`ShowContextMenu`](accesskit::Action::ShowContextMenu) action.
    Accessibility,
}

impl ContextMenuTrigger {
    /// Whether the factory's point is one the user pointed at.
    pub const fn is_pointer(self) -> bool {
        matches!(self, Self::Pointer)
    }
}

/// Temporary storage for handlers and metadata accumulated via builder
/// methods. Transferred to the `WidgetNode` during arena insertion.
pub struct HandlerSet {
    pub(crate) handlers: EventHandlers,
    pub(crate) focusable: Option<bool>,
    pub(crate) tab_index: Option<i32>,
    pub(crate) cursor: Option<CursorIcon>,
    pub(crate) clips_children: Option<bool>,
    /// When `Some(..)`, declares the node a text-input surface and the OS
    /// input method is enabled (with this purpose) while it is focused.
    /// `None` leaves the node default (no OS IME). The platform reads the
    /// focused node's descriptor at focus-change time. See [`crate::ime`].
    pub(crate) ime: Option<crate::ime::ImeContext>,
    /// When `Some(true)`, the widget node is invisible to pointer
    /// hit-testing — events fall through to whatever sits behind it.
    /// Used by the debug inspector's overlay widgets.
    pub(crate) event_pass_through: Option<bool>,
    /// When `Some(true)`, a press in this node's subtree must not arm a
    /// drag/swipe on any ancestor above it (a *gesture dead zone*). See
    /// [`super::arena::WidgetNode::gesture_dead_zone`].
    pub(crate) gesture_dead_zone: Option<bool>,
    /// When `Some(..)`, selects what a **hold** on this node's subtree means for
    /// the tree-owned long-press route. See
    /// [`super::arena::WidgetNode::long_press_role`].
    pub(crate) long_press_role: Option<crate::widget_tree::touch_route::LongPressRole>,
    /// When `Some(..)`, overrides what a direct pointer may do to this
    /// node's subtree. See [`super::arena::WidgetNode::touch_action`].
    pub(crate) touch_action: Option<TouchAction>,
    /// When `Some(..)`, declares this node a pan surface. See
    /// [`super::arena::WidgetNode::pan_claim`].
    pub(crate) pan_claim: Option<PanClaim>,
    pub(crate) overscroll_behavior: Option<crate::OverscrollBehavior>,
    /// When `Some(..)`, overrides when a drag on this node may begin. See
    /// [`super::arena::WidgetNode::drag_activation`].
    pub(crate) drag_activation: Option<teksilo_tokens::DragActivation>,

    /// How many simultaneous contacts this node's recognizers serve. See
    /// [`super::arena::WidgetNode::multi_contact`].
    pub(crate) multi_contact: Option<MultiContact>,
    /// When `Some(true)` and this node holds keyboard focus, a `KeyDown`
    /// bypasses shortcut resolution and is delivered straight to it (a
    /// *keyboard capture* surface — terminals, game viewports). See
    /// [`super::arena::WidgetNode::keyboard_capture`].
    pub(crate) keyboard_capture: Option<bool>,
    /// When `Some(true)`, this node and its WHOLE subtree are invisible
    /// to pointer hit-testing (decorative overlays — count badges,
    /// watermarks). See [`super::arena::WidgetNode::hit_transparent`].
    pub(crate) hit_transparent: Option<bool>,
    /// Per-node override of the *miss-only* slop this node may earn. Second
    /// link of the precedence chain. See [`HandlerSet::hit_slop`].
    pub(crate) hit_slop: Option<crate::pointer::hit_slop::HitSlop>,
    /// When `Some(true)`, this node is excluded from BOTH hit-widening
    /// mechanisms. Head of the precedence chain. See
    /// [`HandlerSet::no_hit_slop`].
    pub(crate) no_hit_slop: Option<bool>,
    pub(crate) context_menu_factory: Option<ContextMenuFactory>,
    /// User-bound signal that the framework writes whenever the
    /// focused widget is a strict descendant of this node. See
    /// [`HandlerSet::focus_within`].
    pub(crate) focus_within: Option<crate::signal::Signal<bool>>,
    /// User-bound signal that the framework writes whenever the
    /// hovered widget is a strict descendant of this node. See
    /// [`HandlerSet::hover_within`].
    pub(crate) hover_within: Option<crate::signal::Signal<bool>>,
    /// User-bound visibility binding (`bool` / `Signal<bool>` / `Prop<bool>`).
    /// Applied at insertion via `WidgetTree::visible_when`, exactly like the
    /// `ctx.visible_when(id, ..)` form, so `teksu!` can write `visible_when: sig`
    /// as a plain widget property. See [`HandlerSet::visible_when`].
    pub(crate) visible_when: Option<Prop<bool>>,
    /// Builder-level accessibility overrides. Mirrored to
    /// `WidgetNode::access_overrides` at insertion. Action callbacks
    /// (`actions`, `custom_actions`) are dispatched by
    /// `pointer_router.rs` when handling
    /// `WidgetEvent::AccessAction`, in addition to the user's
    /// `on_access_action` / `on_access_action_request` handlers — so
    /// builder order doesn't matter.
    pub(crate) access: Option<Box<AccessibilityOverrides>>,
    /// Subtree visibility / merge mode. Mirrored to
    /// `WidgetNode::access_subtree`.
    pub(crate) access_subtree: Option<AccessSubtreeMode>,
}

impl HandlerSet {
    /// Absorb `base`'s declarations wherever `self` is silent.
    ///
    /// `self` is the **later** declaration and wins on conflict, so this reads
    /// left to right like the builder chain that produced the two sets. It is
    /// Compose's `Modifier.then`, expressed on the value Teksilo already has.
    ///
    /// The accessibility block is **merged, not assigned**: an overrides block
    /// carries lists (`controls`, `described_by`, `custom_actions`, ...) that a
    /// plain assignment would drop. `WidgetArena` makes the same point at its
    /// own merge site.
    pub fn merge_under(&mut self, mut base: HandlerSet) {
        macro_rules! take_if_empty {
            ($($field:ident),* $(,)?) => {
                $( if self.$field.is_none() { self.$field = base.$field.take(); } )*
            };
        }
        take_if_empty!(
            focusable,
            tab_index,
            cursor,
            clips_children,
            ime,
            event_pass_through,
            gesture_dead_zone,
            long_press_role,
            touch_action,
            pan_claim,
            overscroll_behavior,
            drag_activation,
            multi_contact,
            keyboard_capture,
            hit_transparent,
            hit_slop,
            no_hit_slop,
            context_menu_factory,
            focus_within,
            hover_within,
            visible_when,
        );
        if self.access_subtree.is_none() {
            self.access_subtree = base.access_subtree.take();
        }
        // `base` is the earlier block, `self` the later one, and
        // `merge_from` lets its argument win — so fold self INTO base and
        // keep the result.
        match (base.access.take(), self.access.take()) {
            (Some(mut earlier), Some(later)) => {
                earlier.merge_from(*later);
                self.access = Some(earlier);
            }
            (earlier, later) => self.access = later.or(earlier),
        }
        self.handlers
            .merge_under(std::mem::take(&mut base.handlers));
    }

    /// Create an empty handler set for use in `BuildContext::apply_self_handlers()`.
    pub fn new() -> Self {
        Self {
            handlers: EventHandlers::new(),
            focusable: None,
            tab_index: None,
            cursor: None,
            clips_children: None,
            ime: None,
            event_pass_through: None,
            gesture_dead_zone: None,
            long_press_role: None,
            drag_activation: None,
            touch_action: None,
            pan_claim: None,
            overscroll_behavior: None,
            multi_contact: None,
            keyboard_capture: None,
            hit_transparent: None,
            hit_slop: None,
            no_hit_slop: None,
            context_menu_factory: None,
            focus_within: None,
            hover_within: None,
            visible_when: None,
            access: None,
            access_subtree: None,
        }
    }

    /// Get a `&mut` to the override block, lazily allocating it on first
    /// access. Used by all `access_*` builder methods.
    pub(crate) fn access_mut(&mut self) -> &mut AccessibilityOverrides {
        self.access
            .get_or_insert_with(|| Box::new(AccessibilityOverrides::default()))
    }

    // -- Builder methods (mirror WidgetWithHandlers) --

    /// Set the on_tap handler. The closure receives a borrowed
    /// [`TapEvent`] carrying the position in
    /// widget-local coordinates, the finalising mouse button, and the
    /// modifier state at that moment.
    ///
    /// Default acceptance is [`ButtonMask::PRIMARY`] — left-click only.
    /// Use [`accept_tap_buttons`](Self::accept_tap_buttons) to widen
    /// the set if you need right-click, middle-click, or auxiliary
    /// buttons to fire this handler.
    pub fn on_tap(mut self, f: impl FnMut(&TapEvent, &mut EventContext) + 'static) -> Self {
        self.handlers.on_tap = Some(Box::new(f));
        self
    }

    /// Set the on_double_tap handler. See [`on_tap`](Self::on_tap) for
    /// the callback contract.
    pub fn on_double_tap(mut self, f: impl FnMut(&TapEvent, &mut EventContext) + 'static) -> Self {
        self.handlers.on_double_tap = Some(Box::new(f));
        self
    }

    /// Set the on_triple_tap handler — fires on the third click within the
    /// recognizer's window (the same `multi_tap_interval` / `multi_tap_slop`
    /// the pointer's gesture profile gives double tap).
    /// Runs independently of `on_double_tap` via cooperative gesture
    /// recognizers (`GestureRecognizer::resets_on_peer_recognition`).
    pub fn on_triple_tap(mut self, f: impl FnMut(&TapEvent, &mut EventContext) + 'static) -> Self {
        self.handlers.on_triple_tap = Some(Box::new(f));
        self
    }

    /// Set the on_long_press handler. The callback receives a borrowed
    /// [`TapEvent`] whose modifiers are
    /// captured from the held `Down` (since long-press recognises on a
    /// timer before any `Up`).
    pub fn on_long_press(mut self, f: impl FnMut(&TapEvent, &mut EventContext) + 'static) -> Self {
        self.handlers.on_long_press = Some(Box::new(f));
        self
    }

    /// Restrict (or extend) the set of pointer buttons that fire
    /// [`on_tap`](Self::on_tap). Default is [`ButtonMask::PRIMARY`]
    /// (left-click only). Pass `ButtonMask::ALL` or
    /// `ButtonMask::PRIMARY | ButtonMask::SECONDARY`, etc.
    ///
    /// The mask belongs to the `on_tap` set beside it. A node carries two
    /// handler sets, the widget's own (from its `build`) and the one this
    /// builder chain attaches, and each fires only on the buttons in its own
    /// mask: widening the app's `on_tap` to the secondary button does not make
    /// a right click run the widget's built-in click (a `Slider` jumping to
    /// it, say). A mask set where no `on_tap` is attached beside it reaches
    /// the widget's own instead, unless that one declared a mask of its own:
    /// `Button::new(..).accept_tap_buttons(PRIMARY | SECONDARY)` is how a
    /// right click activates a button.
    pub fn accept_tap_buttons(mut self, mask: impl Into<ButtonMask>) -> Self {
        self.handlers.tap_buttons = Some(mask.into());
        self
    }

    /// Restrict (or extend) the set of pointer buttons that fire
    /// [`on_double_tap`](Self::on_double_tap). Default
    /// [`ButtonMask::PRIMARY`].
    ///
    /// Scoped to the handler set it is attached with, the way
    /// [`accept_tap_buttons`](Self::accept_tap_buttons) is.
    pub fn accept_double_tap_buttons(mut self, mask: impl Into<ButtonMask>) -> Self {
        self.handlers.double_tap_buttons = Some(mask.into());
        self
    }

    /// Restrict (or extend) the set of pointer buttons that fire
    /// [`on_triple_tap`](Self::on_triple_tap). Default
    /// [`ButtonMask::PRIMARY`].
    ///
    /// Scoped to the handler set it is attached with, the way
    /// [`accept_tap_buttons`](Self::accept_tap_buttons) is.
    pub fn accept_triple_tap_buttons(mut self, mask: impl Into<ButtonMask>) -> Self {
        self.handlers.triple_tap_buttons = Some(mask.into());
        self
    }

    /// Restrict (or extend) the set of pointer buttons that fire
    /// [`on_long_press`](Self::on_long_press). Default
    /// [`ButtonMask::PRIMARY`].
    ///
    /// Scoped to the handler set it is attached with, the way
    /// [`accept_tap_buttons`](Self::accept_tap_buttons) is.
    pub fn accept_long_press_buttons(mut self, mask: impl Into<ButtonMask>) -> Self {
        self.handlers.long_press_buttons = Some(mask.into());
        self
    }

    /// Set the on_hover handler.
    pub fn on_hover(mut self, f: impl FnMut(bool, &mut EventContext) + 'static) -> Self {
        self.handlers.on_hover = Some(Box::new(f));
        self
    }

    /// Set the on_key handler.
    pub fn on_key(
        mut self,
        f: impl FnMut(&WidgetEvent, &mut EventContext) -> EventResponse + 'static,
    ) -> Self {
        self.handlers.on_key = Some(Box::new(f));
        self
    }

    /// Set the strict-ancestor key preview handler. Fires on every
    /// ancestor of the focused widget (root → parent-of-target)
    /// before the focused widget's `on_key` runs. Return
    /// `EventResponse::Handled` to consume the event.
    pub fn on_key_preview(
        mut self,
        f: impl FnMut(&WidgetEvent, &mut EventContext) -> EventResponse + 'static,
    ) -> Self {
        self.handlers.on_key_preview = Some(Box::new(f));
        self
    }

    /// Set the on_drag handler (gesture-based drag). The closure receives
    /// a [`DragPhase`] — `Started`, then zero or more `Moved`, then
    /// `Ended`.
    pub fn on_drag(mut self, f: impl FnMut(DragPhase, &mut EventContext) + 'static) -> Self {
        self.handlers.on_drag = Some(Box::new(f));
        self
    }

    /// Set the on_swipe handler. Fires once per swipe with the direction
    /// and velocity (pixels/second).
    pub fn on_swipe(
        mut self,
        f: impl FnMut(SwipeDirection, f32, &mut EventContext) + 'static,
    ) -> Self {
        self.handlers.on_swipe = Some(Box::new(f));
        self
    }

    /// Set the on_pinch handler. On desktop the phases are produced from
    /// OS trackpad gestures (winit `PinchGesture` / `RotationGesture`).
    pub fn on_pinch(mut self, f: impl FnMut(PinchPhase, &mut EventContext) + 'static) -> Self {
        self.handlers.on_pinch = Some(Box::new(f));
        self
    }

    /// Set the on_focus handler. `f` is called with `true` on focus gain and
    /// `false` on focus loss.
    ///
    /// **WCAG 3.2.1 (On Focus).** Use this only to update *local* visual or
    /// reactive state. Do NOT open a window, navigate, submit, or otherwise
    /// change context from here: a context change triggered merely by a control
    /// receiving focus is a Success Criterion 3.2.1 failure — keyboard users
    /// tabbing through the UI would trigger it unexpectedly. (A debug-only guard
    /// warns if `ctx.open_window(...)` / `ctx.focus_window(...)` is called from
    /// inside focus dispatch.)
    pub fn on_focus(mut self, f: impl FnMut(bool, &mut EventContext) + 'static) -> Self {
        self.handlers.on_focus = Some(Box::new(f));
        self
    }

    /// Set the on_pointer_event handler (low-level escape hatch).
    pub fn on_pointer_event(
        mut self,
        f: impl FnMut(&WidgetEvent, &mut EventContext) -> EventResponse + 'static,
    ) -> Self {
        self.handlers.on_pointer_event = Some(Box::new(f));
        self
    }

    /// Set the on_scroll handler.
    pub fn on_scroll(
        mut self,
        f: impl FnMut(&WidgetEvent, &mut EventContext) -> EventResponse + 'static,
    ) -> Self {
        self.handlers.on_scroll = Some(Box::new(f));
        self
    }

    /// Set the on_access_action handler.
    pub fn on_access_action(
        mut self,
        f: impl FnMut(accesskit::Action, &mut EventContext) -> EventResponse + 'static,
    ) -> Self {
        self.handlers.on_access_action = Some(Box::new(f));
        self
    }

    /// Set the full AccessKit action-request handler. Receives the
    /// action, target NodeId (may be a synthetic widget-emitted
    /// child), and optional `ActionData` payload (e.g.
    /// `SetTextSelection(TextSelection)` or `Value(Box<str>)`).
    ///
    /// Layered with [`on_access_action`](Self::on_access_action) rather than
    /// replacing it: both fire for the same dispatched action, and it counts as
    /// handled if either says so.
    pub fn on_access_action_request(
        mut self,
        f: impl FnMut(
            accesskit::Action,
            accesskit::NodeId,
            Option<accesskit::ActionData>,
            &mut EventContext,
        ) -> EventResponse
        + 'static,
    ) -> Self {
        self.handlers.on_access_action_request = Some(Box::new(f));
        self
    }

    /// Set the focusable flag.
    pub fn focusable(mut self, focusable: bool) -> Self {
        self.focusable = Some(focusable);
        self
    }

    /// Set the cursor icon.
    pub fn cursor(mut self, cursor: CursorIcon) -> Self {
        self.cursor = Some(cursor);
        self
    }

    /// Set the clips_children flag.
    pub fn clips_children(mut self, clips: bool) -> Self {
        self.clips_children = Some(clips);
        self
    }

    /// Declare this node a text-input surface, enabling the OS input method
    /// (with `ctx`'s purpose) while it is focused. Leaving it unset (the
    /// default) means no OS IME. The platform reads the focused node's
    /// descriptor at focus-change time. See [`crate::ime`].
    pub fn ime_input(mut self, ctx: crate::ime::ImeContext) -> Self {
        self.ime = Some(ctx);
        self
    }

    /// Make the widget invisible to pointer hit-testing. With
    /// `pass_through = true`, pointer events traverse this node as if
    /// it were not there — useful for purely decorative overlays that
    /// must not absorb clicks (the debug inspector's `HighlightLayer`
    /// and `HoverProbe` use this).
    pub fn event_pass_through(mut self, pass_through: bool) -> Self {
        self.event_pass_through = Some(pass_through);
        self
    }

    /// Mark this widget's subtree a **gesture dead zone**: a pointer press
    /// inside it must not arm a drag/swipe recognizer on any ancestor above
    /// it. Use to let interactive controls (buttons, a `⋮` menu) sit inside a
    /// draggable / swipeable container (a dock-panel header, a card, a list
    /// row) without a few px of click jitter starting the ancestor's drag.
    /// The container's own drag still works everywhere else. Honored by
    /// `PointerSequence` member enrolment; see the `DeadZone` wrapper widget.
    pub fn gesture_dead_zone(mut self, dead_zone: bool) -> Self {
        self.gesture_dead_zone = Some(dead_zone);
        self
    }

    /// Select what a **hold** on this widget's subtree means, for the
    /// tree-owned long-press route.
    ///
    /// Only ever consulted for a pointer that cannot hover, and only where the
    /// widget installs no `on_long_press` of its own — that always wins. See
    /// [`crate::widget_tree::touch_route`] for the precedence and for what each
    /// variant selects.
    pub fn long_press_role(mut self, role: crate::widget_tree::touch_route::LongPressRole) -> Self {
        self.long_press_role = Some(role);
        self
    }

    /// Override what a direct pointer (touch, pen) is permitted to do to
    /// this widget's subtree — the CSS `touch-action` model. Intersected
    /// with every ancestor's declaration on the way down; a mouse never
    /// consults this. See [`super::arena::WidgetNode::touch_action`].
    pub fn touch_action(mut self, action: TouchAction) -> Self {
        self.touch_action = Some(action);
        self
    }

    /// Declare this widget a **pan surface** on `axes` for direct pointers,
    /// with kinetic (fling/settle) hand-off on release. Sugar for
    /// `.pan_claim(PanClaim { axes, devices: PointerKindMask::DIRECT, kinetic: true })`
    /// — the shape every scrollable declares. See
    /// [`super::arena::WidgetNode::pan_claim`].
    pub fn scroll_container(mut self, axes: PanAxes) -> Self {
        self.pan_claim = Some(PanClaim {
            axes,
            devices: teksilo_tokens::PointerKindMask::DIRECT,
            kinetic: true,
        });
        self
    }

    /// Declare this widget a pan surface with an explicit [`PanClaim`] —
    /// the escape hatch behind [`scroll_container`](Self::scroll_container)
    /// for a claim that isn't kinetic, or that widens/narrows the device
    /// mask. See [`super::arena::WidgetNode::pan_claim`].
    pub fn pan_claim(mut self, claim: PanClaim) -> Self {
        self.pan_claim = Some(claim);
        self
    }

    /// Whether this widget absorbs a scroll it cannot use
    /// ([`Contain`](crate::OverscrollBehavior::Contain)) or lets it chain
    /// outward at its boundary ([`Chain`](crate::OverscrollBehavior::Chain),
    /// the default). The CSS `overscroll-behavior` model, read by the pan
    /// claimant chain. See [`super::arena::WidgetNode::overscroll_behavior`].
    pub fn overscroll_behavior(mut self, behavior: crate::OverscrollBehavior) -> Self {
        self.overscroll_behavior = Some(behavior);
        self
    }

    /// When a drag on this widget may begin relative to the press that starts
    /// it.
    ///
    /// [`DragActivation::Auto`](teksilo_tokens::DragActivation::Auto) — the
    /// default — is `Immediate` for a precise pointer, which is exactly
    /// today's behaviour, and `AfterLongPress` for a coarse pointer whose axis
    /// a pan surface has already claimed. Declare
    /// [`Immediate`](teksilo_tokens::DragActivation::Immediate) for a control
    /// whose drag *is* the interaction (a slider thumb, a splitter handle) and
    /// [`AfterLongPress`](teksilo_tokens::DragActivation::AfterLongPress) for
    /// one that must not steal a scroll (a reorderable list row). See
    /// [`super::arena::WidgetNode::drag_activation`].
    pub fn drag_activation(mut self, activation: teksilo_tokens::DragActivation) -> Self {
        self.drag_activation = Some(activation);
        self
    }

    /// How many simultaneous contacts this node serves. Default
    /// [`MultiContact::First`]. See
    /// [`super::arena::WidgetNode::multi_contact`].
    pub fn multi_contact(mut self, policy: MultiContact) -> Self {
        self.multi_contact = Some(policy);
        self
    }

    /// Mark this widget a **keyboard capture** surface: while it holds
    /// focus, every `KeyDown` is delivered straight to its `on_key`
    /// handler, bypassing shortcut → intent → action resolution. Use for
    /// a terminal emulator that must forward `Ctrl+C` / `Ctrl+W` /
    /// `Alt+<letter>` to a child process instead of triggering the host
    /// app's shortcuts, a game viewport, or a modal text surface.
    ///
    /// # The escape contract
    ///
    /// **`Ctrl+Tab` / `Ctrl+Shift+Tab` are reserved and always move focus
    /// out.** The dispatcher cycles focus on that chord before the capture
    /// node is consulted, so a capture surface cannot become a keyboard trap
    /// (WCAG 2.1.2) however greedily its `on_key` behaves. Do not bind them.
    ///
    /// Nothing else is reserved. In particular Escape is **not**: overlay
    /// back-navigation runs first only while an overlay is actually open, so
    /// a focused capture surface with no overlay above it does receive
    /// Escape and may consume it. See
    /// [`super::arena::WidgetNode::keyboard_capture`].
    pub fn keyboard_capture(mut self, capture: bool) -> Self {
        self.keyboard_capture = Some(capture);
        self
    }

    /// Make this widget AND its whole subtree invisible to pointer
    /// hit-testing. Stronger than [`event_pass_through`](Self::event_pass_through):
    /// that one keeps descendants hittable, this one excludes them too.
    /// For purely decorative composite overlays (a count badge over a
    /// button, a watermark) whose own children would otherwise swallow
    /// the click meant for the control underneath.
    pub fn hit_transparent(mut self, transparent: bool) -> Self {
        self.hit_transparent = Some(transparent);
        self
    }

    /// Override how far a *missed* press may be re-attributed to this node, and
    /// up to what size it is topped up.
    ///
    /// Second link of the precedence chain: `no_hit_slop` beats this, this
    /// beats the widget's own `Widget::hit_slop`, and that beats the density
    /// default. Use it for a control the framework cannot recognise as small —
    /// a hand-drawn handle, a custom mark in a chart — or to raise `up_to`
    /// beyond the density's `target_size` for one especially fiddly target.
    ///
    /// Hit-only: no layout moves and nothing repaints differently.
    pub fn hit_slop(mut self, slop: crate::pointer::hit_slop::HitSlop) -> Self {
        self.hit_slop = Some(slop);
        self
    }

    /// Take this node out of **both** hit-widening mechanisms: it earns no slop
    /// outset, and its `Widget::hit_outset` is ignored.
    ///
    /// Head of the precedence chain, and the right switch for a node whose
    /// exact rectangle is the contract — a surface hosting foreign content
    /// (a `WebView`, an embedded engine) that must receive precisely the
    /// presses that land on it and no others, or a modal scrim, which must
    /// never re-attribute a press to something under it.
    ///
    /// Per-node, not per-subtree: descendants may still widen. To take a whole
    /// subtree out of hit-testing use
    /// [`hit_transparent`](Self::hit_transparent).
    pub fn no_hit_slop(mut self) -> Self {
        self.no_hit_slop = Some(true);
        self
    }

    /// Bind a user-owned `Signal<bool>` that the framework will set
    /// to `true` whenever the focused widget is a *strict descendant*
    /// of this node, and `false` otherwise. Useful for unified focus
    /// halos around composite widgets (a chat composer that highlights
    /// when its `RichTextEditor` or "Send" button is focused, a
    /// `Panel` wrapping a `SpinBox`, etc).
    ///
    /// Strict-ancestors only — a widget that *is* itself focused does
    /// not also see its own `focus_within` signal flipped to `true`.
    /// Combine with `on_focus` if you want both behaviours.
    pub fn focus_within(mut self, signal: crate::signal::Signal<bool>) -> Self {
        self.focus_within = Some(signal);
        self
    }

    /// Bind a user-owned `Signal<bool>` that the framework will set
    /// to `true` whenever the hovered widget is a *strict descendant*
    /// of this node. Symmetric to [`focus_within`](Self::focus_within).
    pub fn hover_within(mut self, signal: crate::signal::Signal<bool>) -> Self {
        self.hover_within = Some(signal);
        self
    }

    /// Bind this node's visibility to a `bool` / `Signal<bool>` / `Prop<bool>`.
    /// A bound value shows/hides the node reactively (registered at
    /// `Relayout`). Equivalent to `ctx.visible_when(id, ..)`; exposed as a
    /// builder method so `teksu!` can write `visible_when: sig` as a property.
    pub fn visible_when(mut self, state: impl Into<Prop<bool>>) -> Self {
        self.visible_when = Some(state.into());
        self
    }

    /// Set a context-menu factory. See [`ContextMenuFactory`] for the
    /// full contract: the closure receives the click position
    /// (window-local) and a full [`EventContext`], and returns
    /// `Some(menu)` to mount or `None` to decline (falling through to
    /// the nearest ancestor with a factory).
    pub fn context_menu(
        mut self,
        factory: impl Fn(Point, &mut EventContext) -> Option<Box<dyn Widget>> + 'static,
    ) -> Self {
        self.context_menu_factory = Some(Box::new(factory));
        self
    }

    /// Set the drag hover handler. Called when a drag payload hovers over this widget.
    /// Return `DropFeedback` to indicate acceptance and visual feedback.
    pub fn on_drag_hover(
        mut self,
        f: impl FnMut(
            &crate::drag_payload::DragPayload,
            teksilo_canvas::Point,
            &mut EventContext,
        ) -> crate::drag_state::DropFeedback
        + 'static,
    ) -> Self {
        self.handlers.on_drag_hover = Some(Box::new(f));
        self
    }

    /// Set the drag-leave handler. Fires when a drag that was over this
    /// widget moves to another target, completes (drop on any target), or
    /// is cancelled. Widgets that stash transient feedback state in
    /// `on_drag_hover` must clear it here.
    pub fn on_drag_leave(mut self, f: impl FnMut(&mut EventContext) + 'static) -> Self {
        self.handlers.on_drag_leave = Some(Box::new(f));
        self
    }

    /// Set the pointer-cancel handler. Fires when a pointer interaction on
    /// this widget is taken away — the window lost focus, a modal opened, the
    /// subtree was parked, a peer won the arbitration.
    ///
    /// **Terminal**: no `PointerUp` follows. Release anything the press
    /// latched; the framework releases its own state but never widget-owned
    /// state.
    pub fn on_pointer_cancel(
        mut self,
        f: impl FnMut(&crate::pointer::PointerInfo, crate::pointer::CancelReason, &mut EventContext)
        + 'static,
    ) -> Self {
        self.handlers.on_pointer_cancel = Some(Box::new(f));
        self
    }

    /// Set the per-frame drag-tick handler. Fires once per frame while a
    /// drag is active and this widget is the current drop target. The
    /// closure receives the current pointer position in widget-local
    /// coordinates. Use for behaviours that must keep running even when
    /// the pointer is stationary — viewport-edge auto-scroll and
    /// spring-loaded folders.
    pub fn on_drag_tick(
        mut self,
        f: impl FnMut(teksilo_canvas::Point, &mut EventContext) + 'static,
    ) -> Self {
        self.handlers.on_drag_tick = Some(Box::new(f));
        self
    }

    /// Set the drop handler. Called when a payload is dropped on this widget.
    /// Return `true` if the drop was accepted.
    pub fn on_drop(
        mut self,
        f: impl FnMut(
            crate::drag_payload::DragPayload,
            teksilo_canvas::Point,
            &mut EventContext,
        ) -> bool
        + 'static,
    ) -> Self {
        self.handlers.on_drop = Some(Box::new(f));
        self
    }

    /// Set the drag-ended handler on a drag **source**. Fires when a drag
    /// this widget started ends — dropped on an in-app target, exported to
    /// another application via the OS (copy / move), or cancelled. Use it to
    /// react to the outcome, e.g. remove the dragged item on a
    /// [`DropOutcome::OsMove`](crate::drag_payload::DropOutcome::OsMove).
    pub fn on_drag_ended(
        mut self,
        f: impl FnMut(crate::drag_payload::DropOutcome, &mut EventContext) + 'static,
    ) -> Self {
        self.handlers.on_drag_ended = Some(Box::new(f));
        self
    }

    /// Advertise a named custom action on this node and register its callback.
    ///
    /// The [`WidgetWithHandlers`] twin
    /// ([`access_custom_action`](WidgetWithHandlers::access_custom_action)) is
    /// how an *application* adds one from outside. This is how a **widget**
    /// adds one to a node it builds itself — a virtualized row, a rail item,
    /// a header cell — where there is no builder chain to hang it on because
    /// the node is reached through
    /// [`BuildContext::apply_handlers`](crate::build_context::BuildContext::apply_handlers).
    ///
    /// Actions are dispatched by declaration order, so a node's callbacks and
    /// its advertised list cannot drift apart.
    pub fn access_custom_action<F>(mut self, label: impl Into<Prop<String>>, handler: F) -> Self
    where
        F: FnMut(&mut EventContext) + 'static,
    {
        self.access_mut()
            .custom_actions
            .push((label.into(), Box::new(handler)));
        self
    }

    /// Finish this node's accessibility with full access to its builder, after
    /// the widget's own `accessibility()` and every typed override.
    ///
    /// The [`WidgetWithHandlers`] twin
    /// ([`access_customize`](WidgetWithHandlers::access_customize)) is the
    /// application's; this one is for a **widget** writing onto a node it
    /// reaches through
    /// [`BuildContext::apply_handlers`](crate::build_context::BuildContext::apply_handlers),
    /// such as a wrapper handing its popup state to the control it wraps.
    /// Chained after any customization the node already carries.
    pub fn access_customize<F>(mut self, f: F) -> Self
    where
        F: Fn(&mut crate::accessibility::AccessNodeBuilder) + 'static,
    {
        self.access_mut().customize = Some(Box::new(f));
        self
    }
}

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

impl std::fmt::Debug for HandlerSet {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("HandlerSet")
            .field("handlers", &self.handlers)
            .field("focusable", &self.focusable)
            .field("tab_index", &self.tab_index)
            .field("cursor", &self.cursor)
            .finish()
    }
}

// ---------------------------------------------------------------------------
// WidgetWithHandlers<W> — wrapper storing widget + accumulated handlers
// ---------------------------------------------------------------------------

/// A widget wrapped with attached event handlers and framework metadata.
/// Created by calling builder methods from `WidgetBuilder` on any widget.
pub struct WidgetWithHandlers<W: Widget> {
    pub(crate) widget: W,
    pub(crate) handler_set: HandlerSet,
    /// Whether [`take_handler_set`](Self::take_handler_set) has run: the
    /// handlers (and cursor, focusability, ...) now live on the arena node,
    /// and `handler_set` is the empty default left behind. Only `Debug` reads
    /// it, so a mounted wrapper does not print an empty set as if it were the
    /// widget's declaration.
    handlers_taken: bool,
}

impl<W: Widget> WidgetWithHandlers<W> {
    fn new(widget: W) -> Self {
        Self {
            widget,
            handler_set: HandlerSet::new(),
            handlers_taken: false,
        }
    }

    /// Take the handler set out, leaving defaults.
    pub(crate) fn take_handler_set(&mut self) -> HandlerSet {
        self.handlers_taken = true;
        std::mem::take(&mut self.handler_set)
    }

    // -- Gesture handlers --

    pub fn on_tap(mut self, f: impl FnMut(&TapEvent, &mut EventContext) + 'static) -> Self {
        self.handler_set.handlers.on_tap = Some(Box::new(f));
        self
    }

    pub fn on_double_tap(mut self, f: impl FnMut(&TapEvent, &mut EventContext) + 'static) -> Self {
        self.handler_set.handlers.on_double_tap = Some(Box::new(f));
        self
    }

    pub fn on_triple_tap(mut self, f: impl FnMut(&TapEvent, &mut EventContext) + 'static) -> Self {
        self.handler_set.handlers.on_triple_tap = Some(Box::new(f));
        self
    }

    pub fn on_long_press(mut self, f: impl FnMut(&TapEvent, &mut EventContext) + 'static) -> Self {
        self.handler_set.handlers.on_long_press = Some(Box::new(f));
        self
    }

    /// Restrict (or extend) the set of pointer buttons that fire
    /// `on_tap`. Default is [`ButtonMask::PRIMARY`].
    ///
    /// The mask belongs to the `on_tap` set beside it. A node carries two
    /// handler sets, the widget's own (from its `build`) and the one this
    /// builder chain attaches, and each fires only on the buttons in its own
    /// mask: widening the app's `on_tap` to the secondary button does not make
    /// a right click run the widget's built-in click (a `Slider` jumping to
    /// it, say). A mask set where no `on_tap` is attached beside it reaches
    /// the widget's own instead, unless that one declared a mask of its own:
    /// `Button::new(..).accept_tap_buttons(PRIMARY | SECONDARY)` is how a
    /// right click activates a button.
    pub fn accept_tap_buttons(mut self, mask: impl Into<ButtonMask>) -> Self {
        self.handler_set.handlers.tap_buttons = Some(mask.into());
        self
    }

    /// Restrict (or extend) the set of pointer buttons that fire
    /// `on_double_tap`. Default [`ButtonMask::PRIMARY`].
    ///
    /// Scoped to the handler set it is attached with, the way
    /// [`accept_tap_buttons`](Self::accept_tap_buttons) is.
    pub fn accept_double_tap_buttons(mut self, mask: impl Into<ButtonMask>) -> Self {
        self.handler_set.handlers.double_tap_buttons = Some(mask.into());
        self
    }

    /// Restrict (or extend) the set of pointer buttons that fire
    /// `on_triple_tap`. Default [`ButtonMask::PRIMARY`].
    ///
    /// Scoped to the handler set it is attached with, the way
    /// [`accept_tap_buttons`](Self::accept_tap_buttons) is.
    pub fn accept_triple_tap_buttons(mut self, mask: impl Into<ButtonMask>) -> Self {
        self.handler_set.handlers.triple_tap_buttons = Some(mask.into());
        self
    }

    /// Restrict (or extend) the set of pointer buttons that fire
    /// `on_long_press`. Default [`ButtonMask::PRIMARY`].
    ///
    /// Scoped to the handler set it is attached with, the way
    /// [`accept_tap_buttons`](Self::accept_tap_buttons) is.
    pub fn accept_long_press_buttons(mut self, mask: impl Into<ButtonMask>) -> Self {
        self.handler_set.handlers.long_press_buttons = Some(mask.into());
        self
    }

    pub fn on_drag(mut self, f: impl FnMut(DragPhase, &mut EventContext) + 'static) -> Self {
        self.handler_set.handlers.on_drag = Some(Box::new(f));
        self
    }

    pub fn on_swipe(
        mut self,
        f: impl FnMut(SwipeDirection, f32, &mut EventContext) + 'static,
    ) -> Self {
        self.handler_set.handlers.on_swipe = Some(Box::new(f));
        self
    }

    pub fn on_pinch(mut self, f: impl FnMut(PinchPhase, &mut EventContext) + 'static) -> Self {
        self.handler_set.handlers.on_pinch = Some(Box::new(f));
        self
    }

    // -- Focus and keyboard --

    pub fn on_focus(mut self, f: impl FnMut(bool, &mut EventContext) + 'static) -> Self {
        self.handler_set.handlers.on_focus = Some(Box::new(f));
        self
    }

    pub fn on_key(
        mut self,
        f: impl FnMut(&WidgetEvent, &mut EventContext) -> EventResponse + 'static,
    ) -> Self {
        self.handler_set.handlers.on_key = Some(Box::new(f));
        self
    }

    /// Set the strict-ancestor key preview handler. See
    /// [`HandlerSet::on_key_preview`].
    pub fn on_key_preview(
        mut self,
        f: impl FnMut(&WidgetEvent, &mut EventContext) -> EventResponse + 'static,
    ) -> Self {
        self.handler_set.handlers.on_key_preview = Some(Box::new(f));
        self
    }

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

    pub fn tab_index(mut self, index: i32) -> Self {
        self.handler_set.tab_index = Some(index);
        self
    }

    // -- Pointer (low-level escape hatch) --

    pub fn on_pointer_event(
        mut self,
        f: impl FnMut(&WidgetEvent, &mut EventContext) -> EventResponse + 'static,
    ) -> Self {
        self.handler_set.handlers.on_pointer_event = Some(Box::new(f));
        self
    }

    pub fn on_hover(mut self, f: impl FnMut(bool, &mut EventContext) + 'static) -> Self {
        self.handler_set.handlers.on_hover = Some(Box::new(f));
        self
    }

    pub fn cursor(mut self, cursor: CursorIcon) -> Self {
        self.handler_set.cursor = Some(cursor);
        self
    }

    // -- Scroll --

    pub fn on_scroll(
        mut self,
        f: impl FnMut(&WidgetEvent, &mut EventContext) -> EventResponse + 'static,
    ) -> Self {
        self.handler_set.handlers.on_scroll = Some(Box::new(f));
        self
    }

    // -- Accessibility actions --

    pub fn on_access_action(
        mut self,
        f: impl FnMut(accesskit::Action, &mut EventContext) -> EventResponse + 'static,
    ) -> Self {
        self.handler_set.handlers.on_access_action = Some(Box::new(f));
        self
    }

    pub fn on_access_action_request(
        mut self,
        f: impl FnMut(
            accesskit::Action,
            accesskit::NodeId,
            Option<accesskit::ActionData>,
            &mut EventContext,
        ) -> EventResponse
        + 'static,
    ) -> Self {
        self.handler_set.handlers.on_access_action_request = Some(Box::new(f));
        self
    }

    // -- Framework-level properties --

    pub fn clips_children(mut self, clips: bool) -> Self {
        self.handler_set.clips_children = Some(clips);
        self
    }

    /// `WidgetBuilder::clips_children_on`'s inherent twin.
    ///
    /// The trait spells it `clips_children_on` because `clips_children` is
    /// already taken on `Widget` as a `&self` query. Without this twin the
    /// trait method applies to an already-wrapped widget and wraps it a second
    /// time; `Widget::take_handler_set` now merges through that, so it is a
    /// wasted node rather than lost behaviour, but the twin avoids both.
    pub fn clips_children_on(self, clips: bool) -> Self {
        self.clips_children(clips)
    }

    /// Declare this node a text-input surface, enabling the OS input method
    /// (with `ctx`'s purpose) while it is focused. See [`crate::ime`].
    pub fn ime_input(mut self, ctx: crate::ime::ImeContext) -> Self {
        self.handler_set.ime = Some(ctx);
        self
    }

    /// Make the widget invisible to pointer hit-testing. See
    /// [`HandlerSet::event_pass_through`].
    pub fn event_pass_through(mut self, pass_through: bool) -> Self {
        self.handler_set.event_pass_through = Some(pass_through);
        self
    }

    /// Mark this widget's subtree a gesture dead zone. See
    /// [`HandlerSet::gesture_dead_zone`].
    pub fn gesture_dead_zone(mut self, dead_zone: bool) -> Self {
        self.handler_set.gesture_dead_zone = Some(dead_zone);
        self
    }

    /// Select what a hold on this widget's subtree means. See
    /// [`HandlerSet::long_press_role`].
    pub fn long_press_role(mut self, role: crate::widget_tree::touch_route::LongPressRole) -> Self {
        self.handler_set.long_press_role = Some(role);
        self
    }

    /// Override what a direct pointer may do to this widget's subtree. See
    /// [`HandlerSet::touch_action`].
    pub fn touch_action(mut self, action: TouchAction) -> Self {
        self.handler_set.touch_action = Some(action);
        self
    }

    /// Declare this widget a pan surface on `axes`, kinetic, direct pointers
    /// only. See [`HandlerSet::scroll_container`].
    pub fn scroll_container(mut self, axes: PanAxes) -> Self {
        self.handler_set.pan_claim = Some(PanClaim {
            axes,
            devices: teksilo_tokens::PointerKindMask::DIRECT,
            kinetic: true,
        });
        self
    }

    /// Declare this widget a pan surface with an explicit [`PanClaim`]. See
    /// [`HandlerSet::pan_claim`].
    pub fn pan_claim(mut self, claim: PanClaim) -> Self {
        self.handler_set.pan_claim = Some(claim);
        self
    }

    /// Whether this widget absorbs a boundary scroll or chains it outward. See
    /// [`HandlerSet::overscroll_behavior`].
    pub fn overscroll_behavior(mut self, behavior: crate::OverscrollBehavior) -> Self {
        self.handler_set.overscroll_behavior = Some(behavior);
        self
    }

    /// When a drag on this widget may begin. See
    /// [`HandlerSet::drag_activation`].
    pub fn drag_activation(mut self, activation: teksilo_tokens::DragActivation) -> Self {
        self.handler_set.drag_activation = Some(activation);
        self
    }

    /// [`HandlerSet::multi_contact`].
    pub fn multi_contact(mut self, policy: MultiContact) -> Self {
        self.handler_set.multi_contact = Some(policy);
        self
    }

    /// Mark this widget a keyboard capture surface: while focused, every
    /// `KeyDown` bypasses shortcut resolution and reaches its `on_key`
    /// handler (terminals, game viewports). See
    /// [`HandlerSet::keyboard_capture`].
    pub fn keyboard_capture(mut self, capture: bool) -> Self {
        self.handler_set.keyboard_capture = Some(capture);
        self
    }

    /// Make this widget and its whole subtree invisible to pointer
    /// hit-testing. See [`HandlerSet::hit_transparent`].
    pub fn hit_transparent(mut self, transparent: bool) -> Self {
        self.handler_set.hit_transparent = Some(transparent);
        self
    }

    /// Override the miss-only hit slop for this node. See
    /// [`HandlerSet::hit_slop`].
    pub fn hit_slop(mut self, slop: crate::pointer::hit_slop::HitSlop) -> Self {
        self.handler_set.hit_slop = Some(slop);
        self
    }

    /// Take this node out of both hit-widening mechanisms. See
    /// [`HandlerSet::no_hit_slop`].
    pub fn no_hit_slop(mut self) -> Self {
        self.handler_set.no_hit_slop = Some(true);
        self
    }

    /// Set a context-menu factory. See
    /// [`HandlerSet::context_menu`] for the full contract.
    pub fn context_menu(
        mut self,
        factory: impl Fn(Point, &mut EventContext) -> Option<Box<dyn Widget>> + 'static,
    ) -> Self {
        self.handler_set.context_menu_factory = Some(Box::new(factory));
        self
    }

    /// Bind a `Signal<bool>` the framework writes when a strict
    /// descendant has focus. See [`HandlerSet::focus_within`].
    pub fn focus_within(mut self, signal: crate::signal::Signal<bool>) -> Self {
        self.handler_set.focus_within = Some(signal);
        self
    }

    /// Bind a `Signal<bool>` the framework writes when a strict
    /// descendant is hovered. See [`HandlerSet::hover_within`].
    pub fn hover_within(mut self, signal: crate::signal::Signal<bool>) -> Self {
        self.handler_set.hover_within = Some(signal);
        self
    }

    /// Bind this node's visibility. See [`HandlerSet::visible_when`].
    pub fn visible_when(mut self, state: impl Into<Prop<bool>>) -> Self {
        self.handler_set.visible_when = Some(state.into());
        self
    }

    /// Set the drag hover handler. Called when a drag payload hovers over this widget.
    pub fn on_drag_hover(
        mut self,
        f: impl FnMut(
            &crate::drag_payload::DragPayload,
            teksilo_canvas::Point,
            &mut EventContext,
        ) -> crate::drag_state::DropFeedback
        + 'static,
    ) -> Self {
        self.handler_set.handlers.on_drag_hover = Some(Box::new(f));
        self
    }

    /// Set the drag-leave handler. See [`HandlerSet::on_drag_leave`].
    pub fn on_drag_leave(mut self, f: impl FnMut(&mut EventContext) + 'static) -> Self {
        self.handler_set.handlers.on_drag_leave = Some(Box::new(f));
        self
    }

    /// Set the pointer-cancel handler. See
    /// [`HandlerSet::on_pointer_cancel`].
    pub fn on_pointer_cancel(
        mut self,
        f: impl FnMut(&crate::pointer::PointerInfo, crate::pointer::CancelReason, &mut EventContext)
        + 'static,
    ) -> Self {
        self.handler_set.handlers.on_pointer_cancel = Some(Box::new(f));
        self
    }

    /// Set the per-frame drag-tick handler. See [`HandlerSet::on_drag_tick`].
    pub fn on_drag_tick(
        mut self,
        f: impl FnMut(teksilo_canvas::Point, &mut EventContext) + 'static,
    ) -> Self {
        self.handler_set.handlers.on_drag_tick = Some(Box::new(f));
        self
    }

    /// Set the drop handler. Called when a payload is dropped on this widget.
    pub fn on_drop(
        mut self,
        f: impl FnMut(
            crate::drag_payload::DragPayload,
            teksilo_canvas::Point,
            &mut EventContext,
        ) -> bool
        + 'static,
    ) -> Self {
        self.handler_set.handlers.on_drop = Some(Box::new(f));
        self
    }

    /// Set the drag-ended handler on a drag source. See
    /// [`HandlerSet::on_drag_ended`].
    pub fn on_drag_ended(
        mut self,
        f: impl FnMut(crate::drag_payload::DropOutcome, &mut EventContext) + 'static,
    ) -> Self {
        self.handler_set.handlers.on_drag_ended = Some(Box::new(f));
        self
    }

    // ── Accessibility overrides ────────────────────────────────────────
    //
    // The user-visible string methods take `impl Into<Prop<String>>` so
    // they stay reactive. With the `i18n` feature, `LocalizedString`
    // (produced by `tr!(...)`) provides `From<LocalizedString> for
    // Prop<String>`, which yields a locale-observing `Prop::Bound`, so
    // `.access_label(tr!(save()))` follows the locale. A bare `&str`
    // still converts (`impl From<&str> for Prop<String>` in `signal.rs`,
    // kept so call sites written against the older `impl Into<String>`
    // setters keep compiling), so routing untranslated literals through
    // `lit!(...)` (downstream crates) or the `_literal` twins (which
    // store `Prop::Static` — the only literal path reachable from within
    // `teksilo-core`) is a convention, not a compiler-enforced one. Do it
    // anyway: it is what makes an untranslated AT string greppable.

    /// Override the accessibility label (`Node::label`) of this widget.
    /// Replaces whatever the inner widget emitted via `set_name`.
    ///
    /// Accepts any `impl Into<Prop<String>>`. With the `i18n` feature,
    /// `LocalizedString` (produced by `tr!(...)`)
    /// implements `From<LocalizedString> for Prop<String>`, so
    /// `.access_label(tr!(save()))` stays reactive — the announced
    /// value re-resolves on locale change (the accessibility tree
    /// re-walks via `sync_accessibility`).
    pub fn access_label(mut self, label: impl Into<Prop<String>>) -> Self {
        self.handler_set.access_mut().label = Some(label.into());
        self
    }

    /// `#[doc(hidden)]` grep marker for explicitly-untranslated label
    /// strings — the same convention as the `lit!` macro downstream, which
    /// replaced the widgets' own `*_literal` constructors. Stores a
    /// `Prop::Static`. The distinct name makes untranslated call sites
    /// greppable as a one-pass audit, and it's the literal path
    /// reachable from within `teksilo-core` (where `lit!` isn't usable).
    #[doc(hidden)]
    pub fn access_label_literal(self, label: impl Into<String>) -> Self {
        self.access_label(Prop::Static(label.into()))
    }

    /// Override the accessibility description (`Node::description`).
    /// Same conversion rules as `access_label`.
    pub fn access_description(mut self, description: impl Into<Prop<String>>) -> Self {
        self.handler_set.access_mut().description = Some(description.into());
        self
    }

    #[doc(hidden)]
    pub fn access_description_literal(self, description: impl Into<String>) -> Self {
        self.access_description(Prop::Static(description.into()))
    }

    /// Long-form context hint. Alias of `access_description` —
    /// AccessKit has no separate hint slot (SwiftUI's split is
    /// VoiceOver-specific). Provided for SwiftUI parity.
    pub fn access_hint(self, hint: impl Into<Prop<String>>) -> Self {
        self.access_description(hint)
    }

    #[doc(hidden)]
    pub fn access_hint_literal(self, hint: impl Into<String>) -> Self {
        self.access_description(Prop::Static(hint.into()))
    }

    /// Override the accessibility value (`Node::value`).
    /// Same conversion rules as `access_label`.
    pub fn access_value(mut self, value: impl Into<Prop<String>>) -> Self {
        self.handler_set.access_mut().value = Some(value.into());
        self
    }

    #[doc(hidden)]
    pub fn access_value_literal(self, value: impl Into<String>) -> Self {
        self.access_value(Prop::Static(value.into()))
    }

    /// Override the accessibility role.
    pub fn access_role(mut self, role: accesskit::Role) -> Self {
        self.handler_set.access_mut().role = Some(role);
        self
    }

    /// Hide (or un-hide) this node, and everything under it, from assistive
    /// technologies. Accepts a plain `bool`, a `Signal<bool>`, or a
    /// `Prop<bool>`: a bound value makes the node appear/disappear from the
    /// AT tree reactively (the binding is registered at `AccessibilityOnly`,
    /// so the tree re-walks on change). `true` hides the whole subtree, as
    /// [`AccessNodeBuilder::set_hidden`](crate::accessibility::AccessNodeBuilder::set_hidden)
    /// explains; to drop only this node's own role and keep its content,
    /// use `access_role(Role::GenericContainer)` instead. `false` un-sets a
    /// hidden state the inner widget emitted on this node, and cannot reveal
    /// a node under a hidden ancestor.
    pub fn access_hidden(mut self, hidden: impl Into<Prop<bool>>) -> Self {
        self.handler_set.access_mut().hidden = Some(hidden.into());
        self
    }

    /// Mark (or un-mark) this widget as disabled for AT. `false`
    /// clears both widget-emitted disabled state AND the framework's
    /// arena-driven disabled gate at
    /// `accessibility_emit_impl::build_accessibility_recursive`.
    pub fn access_disabled(mut self, disabled: bool) -> Self {
        self.handler_set.access_mut().disabled = Some(disabled);
        self
    }

    /// Stable test/debug identifier (`Node::author_id`). Not
    /// user-visible — used by accessibility inspectors and UI tests.
    pub fn access_identifier(mut self, id: impl Into<String>) -> Self {
        self.handler_set.access_mut().identifier = Some(id.into());
        self
    }

    /// Append a `controls` relationship. The target widget's NodeId
    /// is included in this node's `aria-controls`-equivalent list.
    pub fn access_controls(mut self, target: WidgetId) -> Self {
        self.handler_set.access_mut().controls.push(target);
        self
    }

    /// Append a `described_by` relationship: `target`'s text describes this
    /// node, as `aria-describedby` does (WCAG 3.3.1 for a field and its error).
    ///
    /// AccessKit 0.25 passes the relation to no screen reader, so the tree
    /// also writes the target's text into this node's `description`, after
    /// any description of its own. That is what a reader says as focus
    /// arrives. The text follows the target, except around focus, where it
    /// would be said twice: while focus stays, and in the update focus leaves,
    /// a text that was not in the description waits (for the next arrival,
    /// or for the next update once focus has gone). On Windows a text a live
    /// region announces in the update focus arrives in is also left out of
    /// that arrival, since NVDA says the announcement; elsewhere the arrival
    /// keeps it, since Orca cuts an announcement to read the new focus.
    /// A message appearing is for a live region to say, the target itself or
    /// an announcement; the description is for coming back.
    pub fn access_described_by(mut self, target: WidgetId) -> Self {
        self.handler_set.access_mut().described_by.push(target);
        self
    }

    /// Append a `labelled_by` relationship.
    pub fn access_labelled_by(mut self, target: WidgetId) -> Self {
        self.handler_set.access_mut().labelled_by.push(target);
        self
    }

    /// Set the live-region politeness (`Node::live`).
    pub fn access_live(mut self, mode: accesskit::Live) -> Self {
        self.handler_set.access_mut().live = Some(mode);
        self
    }

    /// Mark this node as the current item within its container
    /// (`aria-current`).
    pub fn access_current(mut self, current: accesskit::AriaCurrent) -> Self {
        self.handler_set.access_mut().aria_current = Some(current);
        self
    }

    /// Pre-formatted shortcut announcement (e.g. `"Ctrl+S"`). Used for
    /// chords NOT routed through the `Shortcut` system — platform-native
    /// keys, app-internal hotkeys not exposed to user rebinding. For
    /// `Shortcut`-registered chords prefer
    /// [`access_shortcut_id`](Self::access_shortcut_id), which tracks
    /// rebinds automatically.
    pub fn access_shortcut_literal(mut self, shortcut: impl Into<String>) -> Self {
        self.handler_set.access_mut().shortcut = Some(shortcut.into());
        self
    }

    /// Bind the announced shortcut to a registered `Shortcut` id (the
    /// same id you pass to `Shortcut::new("app.save")`). The
    /// accessibility tree walker resolves the current keystroke from
    /// `WidgetTree::shortcut_registry()` at AT-build time, formats it
    /// via `KeyStroke::Display` (`"Ctrl+S"`), and writes it to
    /// `Node::keyboard_shortcut`. Auto-refreshes on rebind.
    ///
    /// If the registry has no entry for `id` (no widget registered the
    /// shortcut yet), the announcement is omitted — same fallback as
    /// `MenuItem::for_shortcut(...)`.
    pub fn access_shortcut_id(mut self, id: impl Into<String>) -> Self {
        self.handler_set.access_mut().shortcut_id = Some(id.into());
        self
    }

    /// Indicate that activating this widget pops up a menu / listbox /
    /// dialog (`aria-haspopup`).
    pub fn access_has_popup(mut self, kind: accesskit::HasPopup) -> Self {
        self.handler_set.access_mut().has_popup = Some(kind);
        self
    }

    /// Override orientation (`Node::orientation`) — used on sliders,
    /// scrollbars, separators.
    pub fn access_orientation(mut self, orientation: accesskit::Orientation) -> Self {
        self.handler_set.access_mut().orientation = Some(orientation);
        self
    }

    /// Prune all descendants from the accessibility tree. The widget's
    /// own AT node is still emitted; only children disappear. Use for
    /// purely decorative composites. Flutter's `excludeSemantics: true`.
    pub fn access_exclude_subtree(mut self) -> Self {
        self.handler_set.access_subtree = Some(AccessSubtreeMode::Exclude);
        self
    }

    /// Lift descendants' labels / descriptions / values / actions into
    /// this widget's AT node, then prune the descendants. The whole
    /// composite reads as a single AT element. Flutter's
    /// `mergeAllDescendants: true` and SwiftUI's
    /// `.accessibilityElement(children: .combine)`.
    pub fn access_merge_subtree(mut self) -> Self {
        self.handler_set.access_subtree = Some(AccessSubtreeMode::Merge);
        self
    }

    /// Set an explicit subtree mode.
    pub fn access_subtree(mut self, mode: AccessSubtreeMode) -> Self {
        self.handler_set.access_subtree = Some(mode);
        self
    }

    /// Override `Node::numeric_value`.
    pub fn access_numeric_value(mut self, value: f64) -> Self {
        self.handler_set.access_mut().numeric_value = Some(value);
        self
    }

    /// Override `Node::min_numeric_value` and `max_numeric_value`.
    pub fn access_numeric_range(mut self, min: f64, max: f64) -> Self {
        let access = self.handler_set.access_mut();
        access.min_numeric_value = Some(min);
        access.max_numeric_value = Some(max);
        self
    }

    /// Override `Node::numeric_value_step`.
    pub fn access_numeric_step(mut self, step: f64) -> Self {
        self.handler_set.access_mut().numeric_step = Some(step);
        self
    }

    /// Advertise an accessibility action and the callback that fires
    /// when AT software invokes it. Multiple `access_action` calls
    /// register separate callbacks for distinct actions; calling twice
    /// with the same action records both — they fire in order.
    pub fn access_action<F>(mut self, action: accesskit::Action, handler: F) -> Self
    where
        F: FnMut(&mut EventContext) + 'static,
    {
        self.handler_set
            .access_mut()
            .actions
            .push((action, Box::new(handler)));
        self
    }

    /// Suppress an action the inner widget emitted (e.g. neutralize
    /// `Action::Click` on a Button used purely as a layout shim).
    /// Applied after the widget's `accessibility()` runs but before
    /// override-advertised actions, so a subsequent `access_action`
    /// for the same action re-advertises it with the override-installed
    /// callback.
    pub fn access_remove_action(mut self, action: accesskit::Action) -> Self {
        self.handler_set.access_mut().removed_actions.push(action);
        self
    }

    /// Advertise a custom-named action (SwiftUI parity:
    /// `.accessibilityAction(named:_:)`). The label is exposed
    /// verbatim by AT software (e.g. VoiceOver's Actions rotor).
    /// Accepts `tr!(...)` via `From<LocalizedString> for Prop<String>`
    /// in `teksilo-i18n`, so the announced name follows the locale.
    pub fn access_custom_action<F>(mut self, label: impl Into<Prop<String>>, handler: F) -> Self
    where
        F: FnMut(&mut EventContext) + 'static,
    {
        self.handler_set
            .access_mut()
            .custom_actions
            .push((label.into(), Box::new(handler)));
        self
    }

    #[doc(hidden)]
    pub fn access_custom_action_literal<F>(self, label: impl Into<String>, handler: F) -> Self
    where
        F: FnMut(&mut EventContext) + 'static,
    {
        self.access_custom_action(Prop::Static(label.into()), handler)
    }

    /// Final escape hatch — invoked after all typed override setters,
    /// with full `&mut AccessNodeBuilder` access (including
    /// `inner_mut()`). Use for synthetic-child surgery (rich text
    /// paragraphs, text runs) or any AccessKit field the typed
    /// surface doesn't cover.
    pub fn access_customize<F>(mut self, f: F) -> Self
    where
        F: Fn(&mut crate::accessibility::AccessNodeBuilder) + 'static,
    {
        self.handler_set.access_mut().customize = Some(Box::new(f));
        self
    }
}

// Delegate all Widget trait methods to the inner widget.
impl<W: Widget> std::fmt::Debug for WidgetWithHandlers<W> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let mut s = f.debug_struct("WidgetWithHandlers");
        s.field("widget", &self.widget);
        if self.handlers_taken {
            // Mounting moved the set to the node; what is left is the empty
            // default, which would read as "no cursor, no handlers".
            s.field("handlers", &format_args!("<moved to the tree>"));
        } else {
            s.field("handler_set", &self.handler_set);
        }
        s.finish()
    }
}

/// Every method of [`Widget`], forwarded to the wrapped widget.
///
/// `WidgetWithHandlers<W>` **replaces** `W` at `W`'s own arena node — the tree
/// never sees `W` again. So a hook this impl does not forward is not overridden,
/// it is gone: the trait's default answers in its place, for every widget any
/// builder method has ever touched. Nothing warns, nothing fails to compile, and
/// the widget goes on building, painting and hit-testing; only the behaviour
/// behind the dropped hook stops, at a call site nowhere near the `.on_tap(..)`
/// that silenced it. A test that drives the hook on a bare widget cannot see
/// this, which is why every hook is also driven through a builder method in the
/// `wrapper_forwarding_tests` module below, and why `missing_trait_methods` is
/// denied here: a method added to `Widget` must fail this impl's lint before it
/// can quietly fail a user's app.
///
/// The methods appear in the order the trait declares them, so the two can be
/// read side by side.
#[deny(clippy::missing_trait_methods)]
impl<W: Widget + 'static> Widget for WidgetWithHandlers<W> {
    /// Forwarded so the name is the widget's. The wrapper's own name identifies
    /// the wrapper, which is never what a census bucket or an inspector row is
    /// asking about.
    fn type_name(&self) -> &'static str {
        self.widget.type_name()
    }

    fn build(
        &mut self,
        ctx: &mut crate::build_context::BuildContext,
    ) -> Vec<crate::widget_id::WidgetId> {
        self.widget.build(ctx)
    }

    fn layout_response(
        &self,
        proposal: teksilo_canvas::SizeProposal,
        ctx: &crate::widget::LayoutContext,
    ) -> crate::widget::LayoutResponse {
        self.widget.layout_response(proposal, ctx)
    }

    /// Forwarded because the opt-out exists to protect a widget whose
    /// `layout_response` is not idempotent. Answering the default here caches
    /// such a widget anyway, and a memoized non-idempotent measure is wrong in a
    /// way no layout assertion localizes.
    fn cacheable_layout(&self) -> bool {
        self.widget.cacheable_layout()
    }

    fn place_children(
        &self,
        bounds: teksilo_canvas::Rect,
        proposal: teksilo_canvas::SizeProposal,
        children: &mut [crate::widget::WidgetPlacement],
        ctx: &crate::widget::LayoutContext,
    ) {
        self.widget.place_children(bounds, proposal, children, ctx)
    }

    fn paint(
        &self,
        bounds: teksilo_canvas::Rect,
        canvas: &mut teksilo_canvas::Canvas,
        ctx: &crate::widget::PaintContext,
    ) {
        self.widget.paint(bounds, canvas, ctx)
    }

    /// The two paint hooks and their `wants_*` gates are forwarded as pairs: the
    /// walker consults the gate and skips the hook when it answers `false`, so a
    /// forwarded hook behind an unforwarded gate never runs, and the widget
    /// reads as having no hook at all rather than as having lost one.
    fn wants_after_paint(&self) -> bool {
        self.widget.wants_after_paint()
    }

    fn after_paint(
        &self,
        view: &crate::widget::WidgetTreeView<'_>,
        ctx: &crate::widget::PaintContext,
    ) {
        self.widget.after_paint(view, ctx)
    }

    fn wants_post_paint(&self) -> bool {
        self.widget.wants_post_paint()
    }

    fn post_paint(
        &self,
        bounds: teksilo_canvas::Rect,
        canvas: &mut teksilo_canvas::Canvas,
        ctx: &crate::widget::PaintContext,
    ) {
        self.widget.post_paint(bounds, canvas, ctx)
    }

    fn accessibility(&self, builder: &mut crate::accessibility::AccessNodeBuilder) {
        self.widget.accessibility(builder)
    }

    fn culls_children(&self) -> bool {
        self.widget.culls_children()
    }

    /// Gate and hook again — see [`Widget::wants_after_paint`].
    fn wants_descendant_redirects(&self) -> bool {
        self.widget.wants_descendant_redirects()
    }

    fn a11y_redirect_descendant(
        &self,
        self_id: crate::widget_id::WidgetId,
        descendant: crate::widget_id::WidgetId,
    ) -> Option<accesskit::NodeId> {
        self.widget.a11y_redirect_descendant(self_id, descendant)
    }

    fn accessible_title_hint(&self) -> Option<String> {
        self.widget.accessible_title_hint()
    }

    fn accessible_title_node(&self) -> Option<crate::widget_id::WidgetId> {
        self.widget.accessible_title_node()
    }

    fn initial_focus_hint(&self) -> Option<crate::widget_id::WidgetId> {
        self.widget.initial_focus_hint()
    }

    fn accessibility_proxy(&self) -> Option<crate::widget_id::WidgetId> {
        self.widget.accessibility_proxy()
    }

    fn context_menu_key_target(&self) -> Option<crate::widget_id::WidgetId> {
        self.widget.context_menu_key_target()
    }

    fn children(&self) -> Vec<crate::widget_id::WidgetId> {
        self.widget.children()
    }

    fn accessibility_children(&self) -> Option<Vec<crate::widget_id::WidgetId>> {
        self.widget.accessibility_children()
    }

    fn as_any(&self) -> Option<&dyn std::any::Any> {
        self.widget.as_any()
    }

    /// Mutable counterpart of [`as_any`](Widget::as_any), forwarded for the
    /// same reason it is.
    ///
    /// A composing container that reads a child's concrete type must see the
    /// same widget whether or not a builder method wrapped it. `MenuList` reads
    /// a `MenuItem` this way for its mnemonic, its type-ahead label, its radio
    /// group and its safe-triangle state; without this forward,
    /// `MenuItem::new(..).context_menu(..)` silently stops being a `MenuItem`
    /// to its parent — no error, just a row that lost all four.
    fn as_any_mut(&mut self) -> Option<&mut dyn std::any::Any> {
        self.widget.as_any_mut()
    }

    fn clips_children(&self) -> bool {
        self.handler_set
            .clips_children
            .unwrap_or_else(|| self.widget.clips_children())
    }

    fn focus_reveal_rect(&self, bounds: teksilo_canvas::Rect) -> Option<teksilo_canvas::Rect> {
        self.widget.focus_reveal_rect(bounds)
    }

    /// The hit-shape family, forwarded for the same reason `as_any` is: a
    /// widget must not stop being itself to the hit test because a builder
    /// method wrapped it.
    ///
    /// A round control that answers `hit_shape` and `hit_distance` loses both
    /// the moment someone writes `.on_tap(..)` on it if these are not
    /// forwarded — and loses them silently, which is the worst way to lose a
    /// hit test. The node-level `.hit_slop(..)` / `.no_hit_slop()` overrides
    /// need no forwarding: they ride the `HandlerSet` onto the node.
    fn hit_shape(&self, local_point: teksilo_canvas::Point, bounds: teksilo_canvas::Rect) -> bool {
        self.widget.hit_shape(local_point, bounds)
    }

    fn accepts_child_hit(&self, child: WidgetId, point: teksilo_canvas::Point) -> bool {
        self.widget.accepts_child_hit(child, point)
    }

    fn hit_outset(
        &self,
        kind: teksilo_tokens::PointerKind,
        tokens: &teksilo_tokens::InputTokens,
    ) -> teksilo_canvas::EdgeInsets {
        self.widget.hit_outset(kind, tokens)
    }

    fn hit_slop(
        &self,
        kind: teksilo_tokens::PointerKind,
        tokens: &teksilo_tokens::InputTokens,
    ) -> Option<crate::pointer::hit_slop::HitSlop> {
        // Disambiguated: `WidgetBuilder::hit_slop(self, HitSlop)` — the
        // consuming builder method — shares this name, exactly as
        // `clips_children` does on both traits.
        Widget::hit_slop(&self.widget, kind, tokens)
    }

    fn hit_distance(
        &self,
        local_point: teksilo_canvas::Point,
        bounds: teksilo_canvas::Rect,
    ) -> Option<f32> {
        self.widget.hit_distance(local_point, bounds)
    }

    fn target_regions(&self, bounds: teksilo_canvas::Rect) -> Vec<crate::partition::TargetRegion> {
        self.widget.target_regions(bounds)
    }

    /// Forwarded because the default is the destructive answer. A container that
    /// keeps memoized panes across a rebuild loses them to a builder method
    /// otherwise, and the loss reads as content that vanishes on an unrelated
    /// state change rather than as a dropped forward.
    fn preserves_children_on_rebuild(&self) -> bool {
        self.widget.preserves_children_on_rebuild()
    }

    /// Forwarded so tooltip content that knows itself to be empty can still say
    /// so. The default is `true`, which shows an empty bubble instead.
    fn tooltip_has_content(&self) -> bool {
        self.widget.tooltip_has_content()
    }

    /// Forwarded because a declaration is how the registry and the rebinding UI
    /// learn a keystroke exists. Dropped, the shortcut is not overridden by
    /// anything — it is simply never registered.
    fn declare_shortcuts(&self) -> Vec<crate::shortcut::Shortcut> {
        self.widget.declare_shortcuts()
    }

    /// The one method here that is **not** a forward, deliberately: it exists so
    /// the arena can lift off the handlers the builder chain just attached, and
    /// those live on the wrapper, not on the widget. Forwarding it would hand
    /// the arena the wrapped widget's set instead and the attached handlers
    /// would never reach the node — which is the whole point of the wrapper.
    ///
    /// The call is the inherent `WidgetWithHandlers::take_handler_set`, not this
    /// one.
    fn take_handler_set(&mut self) -> Option<HandlerSet> {
        // Recursive, because a `WidgetBuilder` method with no inherent twin on
        // this type wraps an already-wrapped widget. Lifting only the outer set
        // silently drops every handler attached before that call.
        let mut outer = WidgetWithHandlers::take_handler_set(self);
        if let Some(inner) = crate::widget::Widget::take_handler_set(&mut self.widget) {
            outer.merge_under(inner);
        }
        Some(outer)
    }
}

// ---------------------------------------------------------------------------
// WidgetBuilder trait — the entry point
// ---------------------------------------------------------------------------

/// Blanket trait providing attached handler methods for all Widget types.
/// The first builder method call wraps the widget in `WidgetWithHandlers`.
pub trait WidgetBuilder: Widget + Sized + 'static {
    fn on_tap(
        self,
        f: impl FnMut(&TapEvent, &mut EventContext) + 'static,
    ) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).on_tap(f)
    }

    fn on_double_tap(
        self,
        f: impl FnMut(&TapEvent, &mut EventContext) + 'static,
    ) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).on_double_tap(f)
    }

    fn on_triple_tap(
        self,
        f: impl FnMut(&TapEvent, &mut EventContext) + 'static,
    ) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).on_triple_tap(f)
    }

    fn on_long_press(
        self,
        f: impl FnMut(&TapEvent, &mut EventContext) + 'static,
    ) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).on_long_press(f)
    }

    /// Restrict (or extend) the set of pointer buttons that fire
    /// `on_tap`. Default is [`ButtonMask::PRIMARY`].
    ///
    /// The mask belongs to the `on_tap` set beside it. A node carries two
    /// handler sets, the widget's own (from its `build`) and the one this
    /// builder chain attaches, and each fires only on the buttons in its own
    /// mask: widening the app's `on_tap` to the secondary button does not make
    /// a right click run the widget's built-in click (a `Slider` jumping to
    /// it, say). A mask set where no `on_tap` is attached beside it reaches
    /// the widget's own instead, unless that one declared a mask of its own:
    /// `Button::new(..).accept_tap_buttons(PRIMARY | SECONDARY)` is how a
    /// right click activates a button.
    fn accept_tap_buttons(self, mask: impl Into<ButtonMask>) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).accept_tap_buttons(mask)
    }

    /// Restrict (or extend) the set of pointer buttons that fire
    /// `on_double_tap`. Default [`ButtonMask::PRIMARY`].
    ///
    /// Scoped to the handler set it is attached with, the way
    /// [`accept_tap_buttons`](Self::accept_tap_buttons) is.
    fn accept_double_tap_buttons(self, mask: impl Into<ButtonMask>) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).accept_double_tap_buttons(mask)
    }

    /// Restrict (or extend) the set of pointer buttons that fire
    /// `on_triple_tap`. Default [`ButtonMask::PRIMARY`].
    ///
    /// Scoped to the handler set it is attached with, the way
    /// [`accept_tap_buttons`](Self::accept_tap_buttons) is.
    fn accept_triple_tap_buttons(self, mask: impl Into<ButtonMask>) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).accept_triple_tap_buttons(mask)
    }

    /// Restrict (or extend) the set of pointer buttons that fire
    /// `on_long_press`. Default [`ButtonMask::PRIMARY`].
    ///
    /// Scoped to the handler set it is attached with, the way
    /// [`accept_tap_buttons`](Self::accept_tap_buttons) is.
    fn accept_long_press_buttons(self, mask: impl Into<ButtonMask>) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).accept_long_press_buttons(mask)
    }

    fn on_drag(
        self,
        f: impl FnMut(DragPhase, &mut EventContext) + 'static,
    ) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).on_drag(f)
    }

    fn on_swipe(
        self,
        f: impl FnMut(SwipeDirection, f32, &mut EventContext) + 'static,
    ) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).on_swipe(f)
    }

    fn on_pinch(
        self,
        f: impl FnMut(PinchPhase, &mut EventContext) + 'static,
    ) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).on_pinch(f)
    }

    fn on_focus(
        self,
        f: impl FnMut(bool, &mut EventContext) + 'static,
    ) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).on_focus(f)
    }

    fn on_key(
        self,
        f: impl FnMut(&WidgetEvent, &mut EventContext) -> EventResponse + 'static,
    ) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).on_key(f)
    }

    /// Strict-ancestor key preview. See [`HandlerSet::on_key_preview`].
    fn on_key_preview(
        self,
        f: impl FnMut(&WidgetEvent, &mut EventContext) -> EventResponse + 'static,
    ) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).on_key_preview(f)
    }

    fn on_pointer_event(
        self,
        f: impl FnMut(&WidgetEvent, &mut EventContext) -> EventResponse + 'static,
    ) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).on_pointer_event(f)
    }

    fn on_hover(
        self,
        f: impl FnMut(bool, &mut EventContext) + 'static,
    ) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).on_hover(f)
    }

    fn on_scroll(
        self,
        f: impl FnMut(&WidgetEvent, &mut EventContext) -> EventResponse + 'static,
    ) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).on_scroll(f)
    }

    fn on_access_action(
        self,
        f: impl FnMut(accesskit::Action, &mut EventContext) -> EventResponse + 'static,
    ) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).on_access_action(f)
    }

    fn focusable(self, focusable: bool) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).focusable(focusable)
    }

    fn tab_index(self, index: i32) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).tab_index(index)
    }

    fn cursor(self, cursor: CursorIcon) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).cursor(cursor)
    }

    fn clips_children_on(self, clips: bool) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).clips_children(clips)
    }

    /// Declare this node a text-input surface, enabling the OS input method
    /// (with `ctx`'s purpose) while it is focused. See [`crate::ime`].
    fn ime_input(self, ctx: crate::ime::ImeContext) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).ime_input(ctx)
    }

    /// Make the widget invisible to pointer hit-testing. See
    /// [`HandlerSet::event_pass_through`].
    fn event_pass_through(self, pass_through: bool) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).event_pass_through(pass_through)
    }

    /// Mark this widget's subtree a gesture dead zone. See
    /// [`HandlerSet::gesture_dead_zone`].
    fn gesture_dead_zone(self, dead_zone: bool) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).gesture_dead_zone(dead_zone)
    }

    /// Select what a hold on this widget's subtree means. See
    /// [`HandlerSet::long_press_role`].
    fn long_press_role(
        self,
        role: crate::widget_tree::touch_route::LongPressRole,
    ) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).long_press_role(role)
    }

    /// Override what a direct pointer may do to this widget's subtree. See
    /// [`HandlerSet::touch_action`].
    fn touch_action(self, action: TouchAction) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).touch_action(action)
    }

    /// Declare this widget a pan surface on `axes`, kinetic, direct pointers
    /// only. See [`HandlerSet::scroll_container`].
    fn scroll_container(self, axes: PanAxes) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).scroll_container(axes)
    }

    /// Declare this widget a pan surface with an explicit [`PanClaim`]. See
    /// [`HandlerSet::pan_claim`].
    fn pan_claim(self, claim: PanClaim) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).pan_claim(claim)
    }

    /// Whether this widget absorbs a boundary scroll or chains it outward. See
    /// [`HandlerSet::overscroll_behavior`].
    fn overscroll_behavior(self, behavior: crate::OverscrollBehavior) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).overscroll_behavior(behavior)
    }

    /// Declare when a drag on this widget may begin relative to the press that
    /// starts it. See [`HandlerSet::drag_activation`].
    fn drag_activation(
        self,
        activation: teksilo_tokens::DragActivation,
    ) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).drag_activation(activation)
    }

    /// Declare how many simultaneous contacts this widget serves. Default
    /// [`MultiContact::First`] — the second finger on a single-contact control
    /// is terminated there rather than reaching an ancestor.
    fn multi_contact(self, policy: MultiContact) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).multi_contact(policy)
    }

    /// Mark this widget a keyboard capture surface (terminals, game
    /// viewports): while focused, `KeyDown`s bypass shortcut resolution.
    /// See [`HandlerSet::keyboard_capture`].
    fn keyboard_capture(self, capture: bool) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).keyboard_capture(capture)
    }

    /// Make this widget and its whole subtree invisible to pointer
    /// hit-testing (decorative overlays). See
    /// [`HandlerSet::hit_transparent`].
    fn hit_transparent(self, transparent: bool) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).hit_transparent(transparent)
    }

    /// Override the miss-only hit slop for this node. See
    /// [`HandlerSet::hit_slop`].
    fn hit_slop(self, slop: crate::pointer::hit_slop::HitSlop) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).hit_slop(slop)
    }

    /// Take this node out of both hit-widening mechanisms — no slop outset and
    /// no `Widget::hit_outset`. See [`HandlerSet::no_hit_slop`].
    fn no_hit_slop(self) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).no_hit_slop()
    }

    /// Set a context-menu factory. See
    /// [`HandlerSet::context_menu`] for the full contract.
    fn context_menu(
        self,
        factory: impl Fn(Point, &mut EventContext) -> Option<Box<dyn Widget>> + 'static,
    ) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).context_menu(factory)
    }

    /// Bind a `Signal<bool>` the framework writes when a strict
    /// descendant has focus. See [`HandlerSet::focus_within`].
    fn focus_within(self, signal: crate::signal::Signal<bool>) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).focus_within(signal)
    }

    /// Bind a `Signal<bool>` the framework writes when a strict
    /// descendant is hovered. See [`HandlerSet::hover_within`].
    fn hover_within(self, signal: crate::signal::Signal<bool>) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).hover_within(signal)
    }

    /// Bind this node's visibility (`bool` / `Signal<bool>` / `Prop<bool>`) as
    /// a builder property, so `teksu!` can write `visible_when: sig`. Equivalent
    /// to `ctx.visible_when(id, ..)`. See [`HandlerSet::visible_when`].
    fn visible_when(self, state: impl Into<Prop<bool>>) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).visible_when(state)
    }

    fn on_drag_hover(
        self,
        f: impl FnMut(
            &crate::drag_payload::DragPayload,
            teksilo_canvas::Point,
            &mut EventContext,
        ) -> crate::drag_state::DropFeedback
        + 'static,
    ) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).on_drag_hover(f)
    }

    fn on_drag_leave(self, f: impl FnMut(&mut EventContext) + 'static) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).on_drag_leave(f)
    }

    fn on_drag_tick(
        self,
        f: impl FnMut(teksilo_canvas::Point, &mut EventContext) + 'static,
    ) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).on_drag_tick(f)
    }

    /// Attach a pointer-cancel handler. See
    /// [`HandlerSet::on_pointer_cancel`].
    fn on_pointer_cancel(
        self,
        f: impl FnMut(&crate::pointer::PointerInfo, crate::pointer::CancelReason, &mut EventContext)
        + 'static,
    ) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).on_pointer_cancel(f)
    }

    fn on_drop(
        self,
        f: impl FnMut(
            crate::drag_payload::DragPayload,
            teksilo_canvas::Point,
            &mut EventContext,
        ) -> bool
        + 'static,
    ) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).on_drop(f)
    }

    /// Set the drag-ended handler on a drag source. See
    /// [`HandlerSet::on_drag_ended`].
    fn on_drag_ended(
        self,
        f: impl FnMut(crate::drag_payload::DropOutcome, &mut EventContext) + 'static,
    ) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).on_drag_ended(f)
    }

    // ── Accessibility overrides ────────────────────────────────────────
    //
    // Trait-level entry points: each method wraps the widget into a
    // `WidgetWithHandlers` (the first builder call in any chain) and
    // forwards to the inherent method of the same name. See
    // `WidgetWithHandlers` for full rustdoc on each method's semantics.
    // For translated strings, `LocalizedString` flows through
    // `impl Into<Prop<String>>` via `teksilo-i18n`'s
    // `From<LocalizedString> for Prop<String>` impl, staying reactive.

    fn access_label(self, label: impl Into<Prop<String>>) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_label(label)
    }

    #[doc(hidden)]
    fn access_label_literal(self, label: impl Into<String>) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_label_literal(label)
    }

    fn access_description(self, description: impl Into<Prop<String>>) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_description(description)
    }

    #[doc(hidden)]
    fn access_description_literal(
        self,
        description: impl Into<String>,
    ) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_description_literal(description)
    }

    fn access_hint(self, hint: impl Into<Prop<String>>) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_hint(hint)
    }

    #[doc(hidden)]
    fn access_hint_literal(self, hint: impl Into<String>) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_hint_literal(hint)
    }

    fn access_value(self, value: impl Into<Prop<String>>) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_value(value)
    }

    #[doc(hidden)]
    fn access_value_literal(self, value: impl Into<String>) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_value_literal(value)
    }

    fn access_role(self, role: accesskit::Role) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_role(role)
    }

    fn access_hidden(self, hidden: impl Into<Prop<bool>>) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_hidden(hidden)
    }

    fn access_disabled(self, disabled: bool) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_disabled(disabled)
    }

    fn access_identifier(self, id: impl Into<String>) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_identifier(id)
    }

    fn access_controls(self, target: WidgetId) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_controls(target)
    }

    fn access_described_by(self, target: WidgetId) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_described_by(target)
    }

    fn access_labelled_by(self, target: WidgetId) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_labelled_by(target)
    }

    fn access_live(self, mode: accesskit::Live) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_live(mode)
    }

    fn access_current(self, current: accesskit::AriaCurrent) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_current(current)
    }

    fn access_shortcut_literal(self, shortcut: impl Into<String>) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_shortcut_literal(shortcut)
    }

    fn access_shortcut_id(self, id: impl Into<String>) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_shortcut_id(id)
    }

    fn access_has_popup(self, kind: accesskit::HasPopup) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_has_popup(kind)
    }

    fn access_orientation(self, orientation: accesskit::Orientation) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_orientation(orientation)
    }

    fn access_exclude_subtree(self) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_exclude_subtree()
    }

    fn access_merge_subtree(self) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_merge_subtree()
    }

    fn access_subtree(self, mode: AccessSubtreeMode) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_subtree(mode)
    }

    fn access_numeric_value(self, value: f64) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_numeric_value(value)
    }

    fn access_numeric_range(self, min: f64, max: f64) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_numeric_range(min, max)
    }

    fn access_numeric_step(self, step: f64) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_numeric_step(step)
    }

    fn access_action<F>(self, action: accesskit::Action, handler: F) -> WidgetWithHandlers<Self>
    where
        F: FnMut(&mut EventContext) + 'static,
    {
        WidgetWithHandlers::new(self).access_action(action, handler)
    }

    fn access_remove_action(self, action: accesskit::Action) -> WidgetWithHandlers<Self> {
        WidgetWithHandlers::new(self).access_remove_action(action)
    }

    fn access_custom_action<F>(
        self,
        label: impl Into<Prop<String>>,
        handler: F,
    ) -> WidgetWithHandlers<Self>
    where
        F: FnMut(&mut EventContext) + 'static,
    {
        WidgetWithHandlers::new(self).access_custom_action(label, handler)
    }

    #[doc(hidden)]
    fn access_custom_action_literal<F>(
        self,
        label: impl Into<String>,
        handler: F,
    ) -> WidgetWithHandlers<Self>
    where
        F: FnMut(&mut EventContext) + 'static,
    {
        WidgetWithHandlers::new(self).access_custom_action_literal(label, handler)
    }

    fn access_customize<F>(self, f: F) -> WidgetWithHandlers<Self>
    where
        F: Fn(&mut crate::accessibility::AccessNodeBuilder) + 'static,
    {
        WidgetWithHandlers::new(self).access_customize(f)
    }
}

// Blanket implementation for all Widget types.
impl<W: Widget + Sized + 'static> WidgetBuilder for W {}

#[cfg(test)]
mod wrapper_forwarding_tests;

#[cfg(test)]
mod tests {
    use super::*;
    use crate::widget::WidgetPlacement;
    use crate::widget_id::WidgetId;
    use crate::widget_tree::WidgetTree;

    #[derive(Debug)]
    struct CompositeLeaf {
        child_id: Option<WidgetId>,
    }

    impl CompositeLeaf {
        fn new() -> Self {
            Self { child_id: None }
        }
    }

    impl Widget for CompositeLeaf {
        fn build(&mut self, ctx: &mut crate::build_context::BuildContext) -> Vec<WidgetId> {
            let child = ctx.add(crate::test_widgets::FillWidget::new());
            self.child_id = Some(child);
            vec![child]
        }

        fn layout_response(
            &self,
            proposal: teksilo_canvas::SizeProposal,
            _ctx: &crate::widget::LayoutContext,
        ) -> crate::widget::LayoutResponse {
            proposal.resolve(120.0, 40.0).into()
        }

        fn place_children(
            &self,
            bounds: teksilo_canvas::Rect,
            _proposal: teksilo_canvas::SizeProposal,
            children: &mut [WidgetPlacement],
            _ctx: &crate::widget::LayoutContext,
        ) {
            for child in children.iter_mut() {
                child.origin = bounds.origin();
                child.size = bounds.size();
            }
        }

        fn children(&self) -> Vec<WidgetId> {
            self.child_id.into_iter().collect()
        }
    }

    #[test]
    fn external_handlers_survive_rebuild() {
        // Regression check: handlers attached externally via the
        // `WidgetBuilder` builder (e.g. `MyCompositeWidget::new().on_tap(...)`)
        // must continue to fire after the widget rebuilds in place.
        // My handler-clearing fix in `rebuild_single_widget` wiped
        // `node.handlers` to stop accumulation of `apply_self_handlers`
        // calls across rebuilds — but the extracted-once-at-insertion
        // HandlerSet is gone by rebuild time and would be lost.
        use std::cell::Cell;
        use std::rc::Rc;

        let tap_count = Rc::new(Cell::new(0_u32));
        let tc = tap_count.clone();

        let mut tree = WidgetTree::new();
        let id = tree.add(CompositeLeaf::new().on_tap(move |_pos, _ctx| {
            tc.set(tc.get() + 1);
        }));
        tree.layout(teksilo_canvas::SizeProposal::exact(200.0, 100.0));

        // Trip a rebuild of the composite — its child gets torn down &
        // rebuilt; node.handlers gets cleared and reset.
        tree.arena_mark_needs_rebuild_for_testing(id);
        tree.layout(teksilo_canvas::SizeProposal::exact(200.0, 100.0));

        // Click through the composite; the externally-attached on_tap
        // must still be wired up.
        tree.click(id);
        assert_eq!(
            tap_count.get(),
            1,
            "externally-attached on_tap must survive a rebuild"
        );
    }

    #[test]
    fn wrapped_composite_widget_still_builds_children() {
        let mut tree = WidgetTree::new();
        let root = tree.add(CompositeLeaf::new().on_tap(|_pos, _ctx| {}));
        tree.layout(teksilo_canvas::SizeProposal::exact(200.0, 100.0));

        assert_eq!(tree.children(root).len(), 1);
    }

    /// A widget that exposes both downcast hooks, like every widget a
    /// composing container reads its child's concrete type through.
    #[derive(Debug)]
    struct Reflective {
        marker: u32,
    }

    impl Widget for Reflective {
        fn layout_response(
            &self,
            proposal: teksilo_canvas::SizeProposal,
            _ctx: &crate::widget::LayoutContext,
        ) -> crate::widget::LayoutResponse {
            proposal.resolve(0.0, 0.0).into()
        }

        fn as_any(&self) -> Option<&dyn std::any::Any> {
            Some(self)
        }

        fn as_any_mut(&mut self) -> Option<&mut dyn std::any::Any> {
            Some(self)
        }
    }

    /// Decorating a widget must not hide its concrete type from a parent that
    /// reads it. `as_any` was already forwarded; `as_any_mut` was not, so a
    /// container reading a child through the mutable hook (`MenuList` does, for
    /// mnemonics, the type-ahead label and radio grouping) silently saw nothing
    /// the moment any builder method was called on that child.
    #[test]
    fn both_downcast_hooks_see_through_the_handler_wrapper() {
        let mut wrapped = Reflective { marker: 7 }.focusable(true);

        let seen = wrapped
            .as_any()
            .and_then(|a| a.downcast_ref::<Reflective>())
            .map(|r| r.marker);
        assert_eq!(seen, Some(7), "as_any must forward through the wrapper");

        let seen_mut = wrapped
            .as_any_mut()
            .and_then(|a| a.downcast_mut::<Reflective>())
            .map(|r| r.marker);
        assert_eq!(
            seen_mut,
            Some(7),
            "as_any_mut must forward through the wrapper too"
        );
    }

    // --- touch-action / pan-claim builder surfaces ---------------------

    /// Surface 1: `HandlerSet`'s own builder methods set its fields
    /// directly — no arena involved.
    #[test]
    fn handler_set_surface_sets_touch_action_and_pan_claim() {
        let hs = HandlerSet::new()
            .touch_action(TouchAction::PAN_Y)
            .scroll_container(PanAxes::BOTH);
        assert_eq!(hs.touch_action, Some(TouchAction::PAN_Y));
        assert_eq!(
            hs.pan_claim,
            Some(PanClaim {
                axes: PanAxes::BOTH,
                devices: teksilo_tokens::PointerKindMask::DIRECT,
                kinetic: true,
            })
        );
    }

    /// Surface 2: `WidgetWithHandlers<W>`'s inherent methods — reached by
    /// chaining a second builder call onto an already-wrapped widget, which
    /// resolves to the inherent impl rather than the blanket trait default.
    #[test]
    fn widget_with_handlers_surface_sets_touch_action_and_pan_claim() {
        let wrapped = crate::test_widgets::FillWidget::new()
            .gesture_dead_zone(false) // promotes to WidgetWithHandlers via the trait
            .touch_action(TouchAction::NONE) // now resolves to the inherent method
            .pan_claim(PanClaim::horizontal());
        assert_eq!(wrapped.handler_set.touch_action, Some(TouchAction::NONE));
        assert_eq!(wrapped.handler_set.pan_claim, Some(PanClaim::horizontal()));
    }

    /// Surface 3: the blanket `WidgetBuilder` trait default method, called
    /// directly on a bare `Widget` and verified end-to-end through the tree
    /// (the widget-authoring call shape apps actually use). Read back
    /// through the two path folds themselves: for a root with no ancestors,
    /// `effective_touch_action` / `pan_candidates` reduce to exactly the
    /// node's own declaration, so this doubles as a sanity check on those
    /// folds' base case.
    #[test]
    fn widget_builder_surface_sets_the_node_fields() {
        let mut tree = WidgetTree::new();
        let id = tree.add(
            crate::test_widgets::FillWidget::new()
                .touch_action(TouchAction::PAN_X)
                .scroll_container(PanAxes::Y),
        );
        tree.layout(teksilo_canvas::SizeProposal::exact(100.0, 100.0));

        assert_eq!(tree.effective_touch_action(id), TouchAction::PAN_X);
        assert_eq!(
            tree.pan_candidates(id, TouchAction::AUTO),
            vec![(
                id,
                PanClaim {
                    axes: PanAxes::Y,
                    devices: teksilo_tokens::PointerKindMask::DIRECT,
                    kinetic: true,
                }
            )]
        );
    }
}