tessera_ui/

focus.rs

//! Focus ownership, traversal, and restoration for interactive UI.
//!
//! ## Usage
//!
//! Register focus targets, scopes, and traversal rules for keyboard and IME
//! input.

use std::{cell::Cell, collections::BTreeMap, ptr::NonNull};

use rustc_hash::{FxHashMap as HashMap, FxHashSet as HashSet};

use crate::{
    NodeId, PxPosition, PxRect,
    component_tree::{
        ComponentNodeMetaDatas, ComponentNodeTree, NodeRole, nearest_replay_boundary_instance_key,
        sibling_index,
    },
    execution_context::{with_execution_context, with_execution_context_mut},
    prop::CallbackWith,
    px::PxSize,
    runtime::{
        TesseraRuntime, focus_read_subscribers, focus_requester_read_subscribers,
        has_persistent_focus_handle, record_replay_boundary_invalidation_for_instance_key,
        schedule_runtime_redraw, track_focus_read_dependency,
        track_focus_requester_read_dependency,
    },
};

const ROOT_SCOPE_ID: FocusHandleId = 0;

const FOCUS_CHANGE_DIRECTION: crate::session::SessionLocal<Cell<Option<FocusDirection>>> =
    crate::session::SessionLocal::new();

struct FocusChangeDirectionGuard(Option<FocusDirection>);

impl Drop for FocusChangeDirectionGuard {
    fn drop(&mut self) {
        FOCUS_CHANGE_DIRECTION.set(self.0);
    }
}

pub(crate) type FocusHandleId = u128;
pub(crate) type FocusRequesterId = u128;

fn next_focus_handle_id() -> FocusHandleId {
    uuid::Uuid::new_v4().as_u128()
}

fn next_focus_requester_id() -> FocusRequesterId {
    uuid::Uuid::new_v4().as_u128()
}

fn with_bound_focus_owner<R>(f: impl FnOnce(&FocusOwner) -> R) -> Option<R> {
    let ptr = with_execution_context(|context| context.current_focus_owner_stack.last().copied())?;
    // SAFETY: The binding guard only pushes a pointer that remains valid for
    // the duration of the handler dispatch on the current thread.
    Some(unsafe { f(ptr.as_ref()) })
}

fn with_bound_focus_owner_mut<R>(f: impl FnOnce(&mut FocusOwner) -> R) -> Option<R> {
    let ptr = with_execution_context(|context| context.current_focus_owner_stack.last().copied())?;
    // SAFETY: The binding guard only pushes a pointer that remains valid for
    // the duration of the handler dispatch on the current thread.
    Some(unsafe { f(&mut *ptr.as_ptr()) })
}

fn with_focus_owner<R>(f: impl FnOnce(&FocusOwner) -> R) -> R {
    let mut f = Some(f);
    if let Some(result) = with_bound_focus_owner(|owner| {
        f.take().expect("focus owner callback should run once")(owner)
    }) {
        return result;
    }
    TesseraRuntime::with(|runtime| {
        f.take().expect("focus owner callback should run once")(
            runtime.component_tree.focus_owner(),
        )
    })
}

fn with_focus_owner_mut<R>(f: impl FnOnce(&mut FocusOwner) -> R) -> R {
    let mut f = Some(f);
    if let Some(result) = with_bound_focus_owner_mut(|owner| {
        f.take().expect("focus owner callback should run once")(owner)
    }) {
        return result;
    }
    let result = TesseraRuntime::with_mut(|runtime| {
        f.take().expect("focus owner callback should run once")(
            runtime.component_tree.focus_owner_mut(),
        )
    });
    flush_pending_focus_callbacks();
    result
}

pub(crate) struct FocusOwnerBindingGuard {
    active: bool,
}

impl Drop for FocusOwnerBindingGuard {
    fn drop(&mut self) {
        if !self.active {
            return;
        }
        with_execution_context_mut(|context| {
            let popped = context.current_focus_owner_stack.pop();
            debug_assert!(popped.is_some(), "focus owner binding stack underflow");
        });
        self.active = false;
    }
}

pub(crate) fn bind_focus_owner(owner: &mut FocusOwner) -> FocusOwnerBindingGuard {
    with_execution_context_mut(|context| {
        context.current_focus_owner_stack.push(NonNull::from(owner));
    });
    FocusOwnerBindingGuard { active: true }
}

/// Focus state for a registered focus node.
///
/// Use this to render focus-dependent UI and distinguish between the primary
/// focused target and its focused ancestors.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum FocusState {
    /// The node is not participating in the active focus path.
    #[default]
    Inactive,
    /// A descendant of this node currently holds focus.
    ActiveParent,
    /// This node currently holds focus.
    Active,
    /// This node currently holds captured focus.
    Captured,
}

impl FocusState {
    /// Returns `true` when this node is in the active focus path.
    pub fn has_focus(self) -> bool {
        !matches!(self, Self::Inactive)
    }

    /// Returns `true` when this node is the primary focused node.
    pub fn is_focused(self) -> bool {
        matches!(self, Self::Active | Self::Captured)
    }

    /// Returns `true` when this node has captured focus.
    pub fn is_captured(self) -> bool {
        matches!(self, Self::Captured)
    }
}

/// Focus traversal direction for owner-level movement.
///
/// These directions are used by [`FocusManager`], [`FocusScopeNode`], and
/// [`FocusGroupNode`] when keyboard or programmatic traversal moves focus.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
pub enum FocusDirection {
    /// Move to the next focusable target in traversal order.
    Next,
    /// Move to the previous focusable target in traversal order.
    Previous,
    /// Move focus upward.
    Up,
    /// Move focus downward.
    Down,
    /// Move focus leftward.
    Left,
    /// Move focus rightward.
    Right,
    /// Enter a nested focus group or scope.
    Enter,
    /// Exit the current focus group or scope.
    Exit,
}

/// Strategy used by a focus traversal policy.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
pub enum FocusTraversalStrategy {
    /// Traverse in declaration order using previous/next semantics.
    Linear,
    /// Traverse horizontally using left/right arrows.
    Horizontal,
    /// Traverse vertically using up/down arrows.
    Vertical,
    /// Traverse spatially using candidate rectangles.
    Spatial,
}

/// Policy applied by a focus scope or group when traversal starts inside it.
///
/// Use policies to describe how a container handles directional keys and
/// whether `Tab` navigation should stay inside the container.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
pub struct FocusTraversalPolicy {
    /// Traversal strategy used for arrow-key navigation.
    pub strategy: FocusTraversalStrategy,
    /// Whether traversal wraps when it reaches either end of the group.
    pub wrap: bool,
    /// Whether `Tab` and `Shift+Tab` should be handled by this policy.
    pub tab_navigation: bool,
    /// Whether the group contributes one stop to global Tab navigation.
    /// The preferred enabled descendant is used on entry; arrows still visit
    /// every traversable descendant.
    pub single_tab_stop: bool,
}

impl FocusTraversalPolicy {
    /// Creates a new traversal policy for the given strategy.
    pub const fn new(strategy: FocusTraversalStrategy) -> Self {
        Self {
            strategy,
            wrap: false,
            tab_navigation: false,
            single_tab_stop: false,
        }
    }

    /// Creates a linear traversal policy.
    pub const fn linear() -> Self {
        Self::new(FocusTraversalStrategy::Linear)
    }

    /// Creates a horizontal traversal policy.
    pub const fn horizontal() -> Self {
        Self::new(FocusTraversalStrategy::Horizontal)
    }

    /// Creates a vertical traversal policy.
    pub const fn vertical() -> Self {
        Self::new(FocusTraversalStrategy::Vertical)
    }

    /// Creates a spatial traversal policy.
    pub const fn spatial() -> Self {
        Self::new(FocusTraversalStrategy::Spatial)
    }

    /// Sets whether traversal wraps when it reaches either end.
    pub const fn wrap(mut self, wrap: bool) -> Self {
        self.wrap = wrap;
        self
    }

    /// Sets whether `Tab` and `Shift+Tab` should be handled inside this
    /// policy owner.
    pub const fn tab_navigation(mut self, tab_navigation: bool) -> Self {
        self.tab_navigation = tab_navigation;
        self
    }

    /// Makes this group a single Tab stop, preferring a descendant marked with
    /// [`FocusProperties::preferred_tab_stop`] and otherwise its first enabled
    /// descendant. Tab leaves the group from any focused descendant.
    pub const fn single_tab_stop(mut self, single_tab_stop: bool) -> Self {
        self.single_tab_stop = single_tab_stop;
        self
    }

    fn scoped_direction(self, direction: FocusDirection) -> Option<FocusDirection> {
        if self.tab_navigation && !self.single_tab_stop {
            match direction {
                FocusDirection::Next | FocusDirection::Previous => return Some(direction),
                _ => {}
            }
        }

        match self.strategy {
            FocusTraversalStrategy::Linear => match direction {
                FocusDirection::Left | FocusDirection::Up => Some(FocusDirection::Previous),
                FocusDirection::Right | FocusDirection::Down => Some(FocusDirection::Next),
                _ => None,
            },
            FocusTraversalStrategy::Horizontal => match direction {
                FocusDirection::Left => Some(FocusDirection::Previous),
                FocusDirection::Right => Some(FocusDirection::Next),
                _ => None,
            },
            FocusTraversalStrategy::Vertical => match direction {
                FocusDirection::Up => Some(FocusDirection::Previous),
                FocusDirection::Down => Some(FocusDirection::Next),
                _ => None,
            },
            FocusTraversalStrategy::Spatial => match direction {
                FocusDirection::Left
                | FocusDirection::Right
                | FocusDirection::Up
                | FocusDirection::Down => Some(direction),
                _ => None,
            },
        }
    }
}

/// A request for scroll containers to reveal a focused rectangle.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct FocusRevealRequest {
    target_bounds: crate::FloatRect,
    viewport_bounds: crate::FloatRect,
    local_to_window: crate::LocalToWindow,
    /// The absolute rectangle of the focused target.
    pub target_rect: PxRect,
    /// The absolute visible viewport of the current reveal container.
    pub viewport_rect: PxRect,
}

impl FocusRevealRequest {
    pub(crate) fn with_geometry(
        target_bounds: crate::FloatRect,
        viewport_bounds: crate::FloatRect,
        local_to_window: crate::LocalToWindow,
    ) -> Self {
        Self {
            target_rect: target_bounds.outward(),
            viewport_rect: viewport_bounds.outward(),
            target_bounds,
            viewport_bounds,
            local_to_window,
        }
    }

    /// Returns the focused rectangle in the reveal container's local units.
    pub fn local_target_bounds(self) -> crate::FloatRect {
        self.local_to_window.inverse_rect(self.target_bounds)
    }

    /// Returns the visible viewport in the reveal container's local units.
    pub fn local_viewport_bounds(self) -> crate::FloatRect {
        self.local_to_window.inverse_rect(self.viewport_bounds)
    }
}

/// Focus properties used when registering a focus node on the current
/// component.
///
/// Use properties to enable or disable focus participation and to declare
/// explicit traversal neighbors for complex layouts.
/// Controls hidden by layout cannot receive focus. Placed controls outside a
/// scroll viewport remain eligible so navigation can reveal them.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct FocusProperties {
    /// Whether this node may receive focus.
    pub can_focus: bool,
    /// Whether this node may be the target of focus requests.
    pub can_request_focus: bool,
    /// Whether traversal should skip this node.
    /// A directly focused skipped target still anchors subsequent traversal.
    pub skip_traversal: bool,
    /// Whether this target is preferred when Tab enters a single-stop group.
    pub preferred_tab_stop: bool,
    /// Explicit target for `Next` traversal.
    pub next: Option<FocusRequester>,
    /// Explicit target for `Previous` traversal.
    pub previous: Option<FocusRequester>,
    /// Explicit target for `Up` traversal.
    pub up: Option<FocusRequester>,
    /// Explicit target for `Down` traversal.
    pub down: Option<FocusRequester>,
    /// Explicit target for `Left` traversal.
    pub left: Option<FocusRequester>,
    /// Explicit target for `Right` traversal.
    pub right: Option<FocusRequester>,
    /// Explicit target when entering a nested focus region.
    pub enter: Option<FocusRequester>,
    /// Explicit target when exiting a focus region.
    pub exit: Option<FocusRequester>,
}

impl FocusProperties {
    /// Creates the default focus properties for focus targets.
    pub fn new() -> Self {
        Self::default()
    }

    /// Sets whether this node may receive focus.
    pub fn can_focus(mut self, can_focus: bool) -> Self {
        self.can_focus = can_focus;
        self
    }

    /// Sets whether this node may be the target of focus requests.
    pub fn can_request_focus(mut self, can_request_focus: bool) -> Self {
        self.can_request_focus = can_request_focus;
        self
    }

    /// Sets whether traversal should skip this node.
    pub fn skip_traversal(mut self, skip_traversal: bool) -> Self {
        self.skip_traversal = skip_traversal;
        self
    }

    /// Prefers this target when entering a group whose traversal policy uses a
    /// single Tab stop. Disabled or skipped targets are never chosen on entry.
    pub fn preferred_tab_stop(mut self, preferred: bool) -> Self {
        self.preferred_tab_stop = preferred;
        self
    }

    /// Sets the explicit requester for `Next` traversal.
    pub fn next(mut self, requester: FocusRequester) -> Self {
        self.next = Some(requester);
        self
    }

    /// Sets the explicit requester for `Previous` traversal.
    pub fn previous(mut self, requester: FocusRequester) -> Self {
        self.previous = Some(requester);
        self
    }

    /// Sets the explicit requester for `Up` traversal.
    pub fn up(mut self, requester: FocusRequester) -> Self {
        self.up = Some(requester);
        self
    }

    /// Sets the explicit requester for `Down` traversal.
    pub fn down(mut self, requester: FocusRequester) -> Self {
        self.down = Some(requester);
        self
    }

    /// Sets the explicit requester for `Left` traversal.
    pub fn left(mut self, requester: FocusRequester) -> Self {
        self.left = Some(requester);
        self
    }

    /// Sets the explicit requester for `Right` traversal.
    pub fn right(mut self, requester: FocusRequester) -> Self {
        self.right = Some(requester);
        self
    }

    /// Sets the explicit requester used when moving focus into a group.
    pub fn enter(mut self, requester: FocusRequester) -> Self {
        self.enter = Some(requester);
        self
    }

    /// Sets the explicit requester used when moving focus out of a group.
    pub fn exit(mut self, requester: FocusRequester) -> Self {
        self.exit = Some(requester);
        self
    }
}

impl Default for FocusProperties {
    fn default() -> Self {
        Self {
            can_focus: true,
            can_request_focus: true,
            skip_traversal: false,
            preferred_tab_stop: false,
            next: None,
            previous: None,
            up: None,
            down: None,
            left: None,
            right: None,
            enter: None,
            exit: None,
        }
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum FocusRegistrationKind {
    Target,
    Scope,
    Group,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) struct FocusRegistration {
    pub(crate) id: FocusHandleId,
    pub(crate) kind: FocusRegistrationKind,
    pub(crate) properties: FocusProperties,
}

impl FocusRegistration {
    pub(crate) fn target(node: FocusNode) -> Self {
        Self {
            id: node.id,
            kind: FocusRegistrationKind::Target,
            properties: FocusProperties::default(),
        }
    }

    pub(crate) fn scope(scope: FocusScopeNode) -> Self {
        Self {
            id: scope.id,
            kind: FocusRegistrationKind::Scope,
            properties: FocusProperties::default().can_focus(false),
        }
    }

    pub(crate) fn group(group: FocusGroupNode) -> Self {
        Self {
            id: group.id,
            kind: FocusRegistrationKind::Group,
            properties: FocusProperties::default()
                .can_focus(false)
                .can_request_focus(false),
        }
    }
}

/// Imperative handle used to request focus for a registered target.
///
/// Requesters are stable handles that can be stored in component state and
/// passed across component boundaries without exposing the underlying focus
/// tree.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub struct FocusRequester {
    id: FocusRequesterId,
}

impl FocusRequester {
    /// Creates a new focus requester.
    pub fn new() -> Self {
        Self {
            id: next_focus_requester_id(),
        }
    }

    /// Requests focus for the bound target.
    ///
    /// An attached target hidden by layout rejects the request. Navigation can
    /// still reveal a placed target outside its scroll viewport.
    pub fn request_focus(&self) {
        with_focus_owner_mut(|owner| owner.request_focus_by_requester(self.id));
    }

    /// Clears focus from the bound target if it currently holds it.
    pub fn clear_focus(&self) {
        with_focus_owner_mut(|owner| owner.clear_focus_by_requester(self.id));
    }

    /// Alias for [`Self::clear_focus`].
    pub fn unfocus(&self) {
        self.clear_focus();
    }

    /// Captures focus on this node, preventing focus from moving elsewhere
    /// until released, force-cleared, hidden by layout, or removed.
    pub fn capture_focus(&self) {
        with_focus_owner_mut(|owner| owner.capture_focus_by_requester(self.id));
    }

    /// Releases captured focus from this node.
    pub fn free_focus(&self) {
        with_focus_owner_mut(|owner| owner.free_focus_by_requester(self.id));
    }

    /// Returns the current focus state for the bound target.
    pub fn state(&self) -> FocusState {
        track_focus_requester_read_dependency(self.id);
        with_focus_owner(|owner| owner.state_of_requester(self.id))
    }

    /// Returns `true` when this node is in the active focus path.
    pub fn has_focus(&self) -> bool {
        self.state().has_focus()
    }

    /// Returns `true` when this node is the primary focused node.
    pub fn is_focused(&self) -> bool {
        self.state().is_focused()
    }

    /// Returns whether the focused target should display a keyboard focus
    /// indicator.
    ///
    /// Pointer presses hide the indicator without releasing focus. Keyboard
    /// input and accessibility focus actions show it; programmatic focus
    /// inherits the most recent input mode. Read this during component
    /// composition.
    pub fn is_focus_visible(&self) -> bool {
        track_focus_requester_read_dependency(self.id);
        with_focus_owner(|owner| owner.is_requester_focus_visible(self.id))
    }

    /// Returns `true` when this node has captured focus.
    pub fn is_captured(&self) -> bool {
        self.state().is_captured()
    }

    pub(crate) fn requester_id(self) -> FocusRequesterId {
        self.id
    }
}

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

/// Persistent focus target handle.
///
/// This is the low-level target identity used by focus modifiers. Most code
/// should prefer [`FocusRequester`] and [`crate::modifier::FocusModifierExt`].
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub(crate) struct FocusNode {
    id: FocusHandleId,
}

impl FocusNode {
    pub(crate) fn new() -> Self {
        Self {
            id: next_focus_handle_id(),
        }
    }

    pub(crate) fn handle_id(self) -> FocusHandleId {
        self.id
    }

    pub(crate) fn from_handle_id(id: FocusHandleId) -> Self {
        Self { id }
    }
}

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

/// Persistent focus scope handle.
///
/// Scopes own restore behavior and provide imperative traversal within a
/// subtree.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub struct FocusScopeNode {
    id: FocusHandleId,
}

impl FocusScopeNode {
    /// Creates a new persistent focus scope handle.
    pub fn new() -> Self {
        Self {
            id: next_focus_handle_id(),
        }
    }

    pub(crate) fn handle_id(self) -> FocusHandleId {
        self.id
    }

    pub(crate) fn from_handle_id(id: FocusHandleId) -> Self {
        Self { id }
    }

    /// Requests focus within this scope, restoring the last focused descendant
    /// when possible.
    pub fn request_focus(&self) {
        with_focus_owner_mut(|owner| owner.request_focus(self.id));
    }

    /// Clears focus from this scope.
    pub fn clear_focus(&self) {
        with_focus_owner_mut(|owner| owner.clear_focus(self.id));
    }

    /// Restores focus to the last focused descendant of this scope.
    pub fn restore_focus(&self) {
        with_focus_owner_mut(|owner| owner.restore_focus(self.id));
    }

    /// Moves focus to another focusable descendant inside this scope.
    pub fn move_focus(&self, direction: FocusDirection) -> bool {
        with_focus_owner_mut(|owner| owner.move_focus_in_scope(self.id, direction, false))
    }

    /// Cycles focus inside this scope, wrapping when traversal reaches an end.
    pub fn cycle_focus(&self, direction: FocusDirection) -> bool {
        with_focus_owner_mut(|owner| owner.move_focus_in_scope(self.id, direction, true))
    }

    /// Returns the current focus state for this scope.
    pub fn state(&self) -> FocusState {
        track_focus_read_dependency(self.id);
        with_focus_owner(|owner| owner.state_of(self.id))
    }

    /// Returns `true` when this scope participates in the active focus path.
    pub fn has_focus(&self) -> bool {
        self.state().has_focus()
    }

    /// Returns `true` when this scope itself is the primary focused node.
    pub fn is_focused(&self) -> bool {
        self.state().is_focused()
    }
}

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

/// Persistent traversal-only focus group handle.
///
/// Groups define traversal boundaries without taking on scope restore
/// semantics.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub struct FocusGroupNode {
    id: FocusHandleId,
}

impl FocusGroupNode {
    /// Creates a new persistent focus group handle.
    pub fn new() -> Self {
        Self {
            id: next_focus_handle_id(),
        }
    }

    pub(crate) fn handle_id(self) -> FocusHandleId {
        self.id
    }

    pub(crate) fn from_handle_id(id: FocusHandleId) -> Self {
        Self { id }
    }

    /// Moves focus to another focusable descendant inside this group.
    pub fn move_focus(&self, direction: FocusDirection) -> bool {
        with_focus_owner_mut(|owner| owner.move_focus_in_scope(self.id, direction, false))
    }

    /// Cycles focus inside this group, wrapping when traversal reaches an end.
    pub fn cycle_focus(&self, direction: FocusDirection) -> bool {
        with_focus_owner_mut(|owner| owner.move_focus_in_scope(self.id, direction, true))
    }

    /// Returns the current focus state for this group.
    pub fn state(&self) -> FocusState {
        track_focus_read_dependency(self.id);
        with_focus_owner(|owner| owner.state_of(self.id))
    }

    /// Returns `true` when this group participates in the active focus path.
    pub fn has_focus(&self) -> bool {
        self.state().has_focus()
    }

    /// Returns `true` when this group itself is the primary focused node.
    pub fn is_focused(&self) -> bool {
        self.state().is_focused()
    }
}

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

/// A saved focus target that can be restored while it remains available.
///
/// Use [`FocusManager::save_focus`] before showing temporary interactive
/// content. Restoration does not wait for a removed or disabled target to
/// become available.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct FocusRestorationTarget {
    id: FocusHandleId,
}

impl FocusRestorationTarget {
    /// Restores focus if the target is attached, enabled and available.
    ///
    /// Returns `false` when the window is unfocused or another target has
    /// captured focus. Check availability after layout when target
    /// properties have changed.
    pub fn restore(self) -> bool {
        with_focus_owner_mut(|owner| {
            if !owner.owner_focused
                || !owner.can_request_focus(self.id)
                || owner.captured.is_some_and(|captured| captured != self.id)
            {
                return false;
            }
            owner.request_focus(self.id);
            true
        })
    }
}

/// Owner-scoped focus manager for traversal and forced clear operations.
///
/// Use the focus manager to trigger application-level traversal without
/// storing a specific scope or requester.
#[derive(Clone, Copy, Debug, Default)]
pub struct FocusManager;

impl FocusManager {
    /// Returns the focus manager for the current component tree.
    pub fn current() -> Self {
        Self
    }

    /// Saves the current target for restoring focus after temporary UI closes.
    ///
    /// Saving does not move focus or keep the target alive. Restore only while
    /// the temporary UI still owns focus, so later user navigation is
    /// preserved.
    pub fn save_focus(self) -> Option<FocusRestorationTarget> {
        with_focus_owner(|owner| owner.active.map(|id| FocusRestorationTarget { id }))
    }

    /// Returns the traversal direction responsible for the focus callback
    /// currently running. Explicit focus requests, restoration, and calls
    /// outside a focus callback return `None`.
    pub fn focus_change_direction(self) -> Option<FocusDirection> {
        FOCUS_CHANGE_DIRECTION.get()
    }

    /// Defers queued keys until the next layout and its focus updates finish.
    ///
    /// Use when opening or closing focusable content so subsequent keys reach
    /// the resulting focus target.
    pub fn defer_keyboard_until_layout(self) {
        with_focus_owner_mut(|owner| owner.keyboard_barrier = KeyboardLayoutBarrier::Requested);
    }

    /// Clears the current focus. Set `force` to `true` to break captured focus.
    pub fn clear_focus(self, force: bool) {
        with_focus_owner_mut(|owner| {
            owner.clear_focus_global(force);
        });
    }

    /// Moves focus in the requested direction.
    pub fn move_focus(self, direction: FocusDirection) -> bool {
        with_focus_owner_mut(|owner| {
            owner.pending_navigation = None;
            owner.move_focus(direction)
        })
    }

    /// Queues traversal after the next layout, revealing lazy content as
    /// needed.
    ///
    /// Later requests replace an earlier queued direction. Returns `false` when
    /// the window is unfocused or focus is captured. Following keyboard input
    /// waits for the requested traversal and its layout updates.
    /// Explicit focus requests, focus capture, and window blur cancel it.
    pub fn request_move_focus(self, direction: FocusDirection) -> bool {
        let accepted = with_focus_owner_mut(|owner| {
            if !owner.owner_focused || owner.captured.is_some() {
                return false;
            }
            owner.pending_navigation = Some(direction);
            owner.keyboard_barrier = KeyboardLayoutBarrier::Requested;
            true
        });
        if accepted {
            schedule_runtime_redraw();
        }
        accepted
    }
}

#[derive(Clone, Copy, Debug)]
struct FocusAttachment {
    host_replay_boundary_key: u64,
    live_node_id: Option<NodeId>,
    focus_rect: Option<PxRect>,
    traversal_order: Option<u64>,
    parent: FocusHandleId,
    scope_parent: FocusHandleId,
}

impl FocusAttachment {
    fn permits_focus(self) -> bool {
        // Requests before layout remain valid. Clipped but placed targets keep
        // a rectangle so keyboard navigation can reveal them.
        self.traversal_order.is_none() || self.focus_rect.is_some()
    }

    fn root_scope() -> Self {
        Self {
            host_replay_boundary_key: 0,
            live_node_id: None,
            focus_rect: None,
            traversal_order: None,
            parent: ROOT_SCOPE_ID,
            scope_parent: ROOT_SCOPE_ID,
        }
    }
}

#[derive(Clone, Copy, Debug)]
struct FocusTreeNode {
    kind: FocusRegistrationKind,
    attachment: Option<FocusAttachment>,
    last_parent: FocusHandleId,
    last_scope_parent: FocusHandleId,
    props: FocusProperties,
    traversal_policy: Option<FocusTraversalPolicy>,
    state: FocusState,
    last_focused_descendant: Option<FocusHandleId>,
    restorer_fallback: Option<FocusRequesterId>,
}

impl FocusTreeNode {
    fn new_root_scope() -> Self {
        Self {
            kind: FocusRegistrationKind::Scope,
            attachment: Some(FocusAttachment::root_scope()),
            last_parent: ROOT_SCOPE_ID,
            last_scope_parent: ROOT_SCOPE_ID,
            props: FocusProperties::default()
                .can_focus(false)
                .can_request_focus(false)
                .skip_traversal(true),
            traversal_policy: None,
            state: FocusState::Inactive,
            last_focused_descendant: None,
            restorer_fallback: None,
        }
    }

    fn new(kind: FocusRegistrationKind) -> Self {
        Self {
            kind,
            attachment: None,
            last_parent: ROOT_SCOPE_ID,
            last_scope_parent: ROOT_SCOPE_ID,
            props: FocusProperties::default(),
            traversal_policy: None,
            state: FocusState::Inactive,
            last_focused_descendant: None,
            restorer_fallback: None,
        }
    }

    fn is_attached(&self) -> bool {
        self.attachment.is_some()
    }
}

#[derive(Clone)]
pub(crate) struct PendingFocusCallbackInvocation {
    callback: CallbackWith<FocusState>,
    state: FocusState,
    direction: Option<FocusDirection>,
}

impl PendingFocusCallbackInvocation {
    pub(crate) fn new(
        callback: CallbackWith<FocusState>,
        state: FocusState,
        direction: Option<FocusDirection>,
    ) -> Self {
        Self {
            callback,
            state,
            direction,
        }
    }

    pub(crate) fn invoke(self) {
        let _direction = FocusChangeDirectionGuard(FOCUS_CHANGE_DIRECTION.replace(self.direction));
        self.callback.call(self.state);
    }
}

#[derive(Clone, Copy, Debug)]
pub(crate) struct FocusNotification {
    pub handle_id: FocusHandleId,
    pub state: FocusState,
    pub changed: bool,
    pub direction: Option<FocusDirection>,
}

#[derive(Clone, Copy, Debug)]
enum FocusCommand {
    Request(FocusHandleId),
    Clear(FocusHandleId),
    Capture(FocusHandleId),
    Free(FocusHandleId),
    Restore(FocusHandleId),
}

#[derive(Clone, Copy)]
struct DeferredFocusCommand {
    command: FocusCommand,
    reveal: bool,
}

#[derive(Clone, Copy, Default, PartialEq, Eq)]
enum KeyboardLayoutBarrier {
    #[default]
    None,
    Requested,
    Layout,
}

type FocusOrderPath = Vec<(u64, usize)>;
type FocusChildren = BTreeMap<(FocusOrderPath, FocusHandleId), FocusHandleId>;

/// Per-component-tree focus owner.
#[derive(Default)]
pub(crate) struct FocusOwner {
    nodes: HashMap<FocusHandleId, FocusTreeNode>,
    children_by_parent: HashMap<FocusHandleId, FocusChildren>,
    requester_bindings: HashMap<FocusRequesterId, FocusHandleId>,
    requesters_by_handle: HashMap<FocusHandleId, Vec<FocusRequesterId>>,
    active: Option<FocusHandleId>,
    stateful_handles: HashSet<FocusHandleId>,
    handles_by_component: HashMap<NodeId, FocusHandleId>,
    order_paths: HashMap<FocusHandleId, FocusOrderPath>,
    captured: Option<FocusHandleId>,
    suspended: Option<FocusHandleId>,
    owner_focused: bool,
    focus_visible: bool,
    latest_focus_input: Option<crate::time::Instant>,
    pending: Vec<DeferredFocusCommand>,
    pending_notifications: Vec<FocusNotification>,
    pending_reveal: Option<FocusHandleId>,
    pending_navigation: Option<FocusDirection>,
    keyboard_barrier: KeyboardLayoutBarrier,
}

impl FocusOwner {
    pub(crate) fn new() -> Self {
        let mut nodes = HashMap::default();
        nodes.insert(ROOT_SCOPE_ID, FocusTreeNode::new_root_scope());
        Self {
            nodes,
            children_by_parent: HashMap::default(),
            requester_bindings: HashMap::default(),
            requesters_by_handle: HashMap::default(),
            active: None,
            stateful_handles: HashSet::default(),
            handles_by_component: HashMap::default(),
            order_paths: HashMap::default(),
            captured: None,
            suspended: None,
            owner_focused: true,
            focus_visible: false,
            latest_focus_input: None,
            pending: Vec::new(),
            pending_notifications: Vec::new(),
            pending_reveal: None,
            pending_navigation: None,
            keyboard_barrier: KeyboardLayoutBarrier::None,
        }
    }

    pub(crate) fn reset(&mut self) {
        *self = Self::new();
    }

    pub(crate) fn begin_layout(&mut self) {
        if self.keyboard_barrier == KeyboardLayoutBarrier::Requested {
            self.keyboard_barrier = KeyboardLayoutBarrier::Layout;
        }
    }

    pub(crate) fn finish_layout(&mut self) {
        if self.keyboard_barrier == KeyboardLayoutBarrier::Layout {
            self.keyboard_barrier = KeyboardLayoutBarrier::None;
        }
    }

    pub(crate) fn keyboard_is_deferred(&self) -> bool {
        self.keyboard_barrier != KeyboardLayoutBarrier::None
    }

    pub(crate) fn take_pending_navigation(&mut self) -> Option<FocusDirection> {
        self.pending_navigation
            .take()
            .filter(|_| self.owner_focused && self.captured.is_none())
    }

    pub(crate) fn retain_navigation_retry(&mut self, direction: Option<FocusDirection>) {
        if self.pending_navigation.is_none() {
            self.pending_navigation = direction;
        }
    }

    pub(crate) fn has_pending_navigation(&self) -> bool {
        self.pending_navigation.is_some()
    }

    pub(crate) fn allows_navigation(&self) -> bool {
        self.owner_focused && self.captured.is_none()
    }

    pub(crate) fn state_of(&self, id: FocusHandleId) -> FocusState {
        self.nodes
            .get(&id)
            .filter(|node| node.is_attached())
            .map(|node| node.state)
            .unwrap_or(FocusState::Inactive)
    }

    pub(crate) fn active_component_node_id(&self) -> Option<NodeId> {
        let active = self.active?;
        self.nodes
            .get(&active)
            .and_then(|node| node.attachment)
            .and_then(|attachment| attachment.live_node_id)
    }

    pub(crate) fn component_node_id_of(&self, id: FocusHandleId) -> Option<NodeId> {
        self.nodes
            .get(&id)
            .and_then(|node| node.attachment)
            .and_then(|attachment| attachment.live_node_id)
    }

    pub(crate) fn active_handle_id(&self) -> Option<FocusHandleId> {
        self.active
    }

    pub(crate) fn has_pending_reveal(&self) -> bool {
        self.pending_reveal.is_some()
    }

    pub(crate) fn take_pending_reveal(&mut self) -> Option<FocusHandleId> {
        self.pending_reveal.take()
    }

    pub(crate) fn retain_reveal_retry(&mut self) {
        if self.pending_reveal.is_none() {
            self.pending_reveal = self.active;
        }
    }

    pub(crate) fn cancel_pending_reveal_for_scroll(&mut self) {
        self.pending_reveal = None;
        for pending in &mut self.pending {
            if matches!(
                pending.command,
                FocusCommand::Request(_) | FocusCommand::Restore(_)
            ) {
                pending.reveal = false;
            }
        }
    }

    pub(crate) fn record_keyboard_input(
        &mut self,
        state: winit::event::ElementState,
        timestamp: crate::time::Instant,
    ) {
        if state == winit::event::ElementState::Pressed {
            self.record_focus_input(true, timestamp);
        }
    }

    pub(crate) fn record_pointer_press(&mut self, timestamp: crate::time::Instant) {
        self.record_focus_input(false, timestamp);
    }

    pub(crate) fn observe_pointer_press(&mut self, timestamp: crate::time::Instant) {
        if self
            .latest_focus_input
            .is_none_or(|latest| timestamp > latest)
        {
            self.record_pointer_press(timestamp);
        }
    }

    pub(crate) fn record_accessibility_focus(&mut self, timestamp: crate::time::Instant) {
        self.record_focus_input(true, timestamp);
    }

    fn record_focus_input(&mut self, visible: bool, timestamp: crate::time::Instant) {
        if self
            .latest_focus_input
            .is_some_and(|latest| timestamp < latest)
        {
            return;
        }
        self.latest_focus_input = Some(timestamp);
        if self.focus_visible == visible {
            return;
        }
        self.focus_visible = visible;
        let Some(active) = self.active else {
            return;
        };
        if let Some(node) = self.nodes.get(&active)
            && let Some(attachment) = node.attachment
            && attachment.host_replay_boundary_key != 0
        {
            record_replay_boundary_invalidation_for_instance_key(
                attachment.host_replay_boundary_key,
            );
        }
        if let Some(requesters) = self.requesters_by_handle.get(&active) {
            for requester in requesters {
                for reader in focus_requester_read_subscribers(*requester) {
                    record_replay_boundary_invalidation_for_instance_key(reader);
                }
            }
        }
    }

    pub(crate) fn is_requester_focus_visible(&self, id: FocusRequesterId) -> bool {
        self.owner_focused && self.focus_visible && self.state_of_requester(id).is_focused()
    }

    pub(crate) fn state_of_requester(&self, id: FocusRequesterId) -> FocusState {
        self.requester_bindings
            .get(&id)
            .copied()
            .map(|handle_id| self.state_of(handle_id))
            .unwrap_or(FocusState::Inactive)
    }

    pub(crate) fn request_focus_by_requester(&mut self, id: FocusRequesterId) {
        if let Some(handle_id) = self.requester_bindings.get(&id).copied() {
            self.request_focus(handle_id);
        }
    }

    pub(crate) fn clear_focus_by_requester(&mut self, id: FocusRequesterId) {
        if let Some(handle_id) = self.requester_bindings.get(&id).copied() {
            self.clear_focus(handle_id);
        }
    }

    pub(crate) fn capture_focus_by_requester(&mut self, id: FocusRequesterId) {
        if let Some(handle_id) = self.requester_bindings.get(&id).copied() {
            self.capture_focus(handle_id);
        }
    }

    pub(crate) fn free_focus_by_requester(&mut self, id: FocusRequesterId) {
        if let Some(handle_id) = self.requester_bindings.get(&id).copied() {
            self.free_focus(handle_id);
        }
    }

    pub(crate) fn request_focus(&mut self, id: FocusHandleId) {
        self.execute_or_defer(FocusCommand::Request(id));
    }

    pub(crate) fn clear_focus(&mut self, id: FocusHandleId) {
        self.execute_or_defer(FocusCommand::Clear(id));
    }

    pub(crate) fn capture_focus(&mut self, id: FocusHandleId) {
        self.execute_or_defer(FocusCommand::Capture(id));
    }

    pub(crate) fn free_focus(&mut self, id: FocusHandleId) {
        self.execute_or_defer(FocusCommand::Free(id));
    }

    pub(crate) fn restore_focus(&mut self, id: FocusHandleId) {
        self.execute_or_defer(FocusCommand::Restore(id));
    }

    pub(crate) fn set_owner_focused(&mut self, focused: bool) {
        if self.owner_focused == focused {
            return;
        }

        let previous_states = self.snapshot_live_states();
        self.owner_focused = focused;
        if !focused {
            self.pending_navigation = None;
        }
        if focused {
            if let Some(suspended) = self.suspended.take() {
                if let Some(target) = self.resolve_request_target(suspended) {
                    self.active = Some(target);
                    self.pending_reveal = Some(target);
                } else {
                    self.suspended = Some(suspended);
                }
            }
        } else {
            self.suspended = self.active;
            self.active = None;
            self.captured = None;
            self.pending_reveal = None;
        }
        self.recompute_states();
        self.notify_state_changes(previous_states);
    }

    pub(crate) fn sync_changes(
        &mut self,
        tree: &ComponentNodeTree,
        changed: &HashSet<NodeId>,
        removed: &HashSet<NodeId>,
    ) {
        if changed.is_empty() && removed.is_empty() {
            return;
        }
        let previous_states = self.snapshot_live_states();
        let mut requesters = HashMap::default();
        for &node_id in removed.iter().chain(changed.iter()) {
            let Some(handle) = self.handles_by_component.remove(&node_id) else {
                continue;
            };
            if let Some(node) = self.nodes.get_mut(&handle) {
                if let Some(attachment) = node.attachment.take() {
                    if let Some(children) = self.children_by_parent.get_mut(&attachment.parent) {
                        if let Some(order) = self.order_paths.get(&handle) {
                            children.remove(&(order.clone(), handle));
                        }
                    }
                }
            }
            if let Some(bindings) = self.requesters_by_handle.remove(&handle) {
                for requester in bindings {
                    let previous = self.requester_bindings.remove(&requester);
                    requesters.entry(requester).or_insert(previous);
                }
            }
        }
        for &node_id in changed {
            let Some(node_ref) = tree.get(node_id).filter(|node| !node.is_removed()) else {
                continue;
            };
            let node = node_ref.get();
            let interaction = node.interaction();
            let Some(registration) = interaction.focus_registration else {
                continue;
            };
            let mut parent = ROOT_SCOPE_ID;
            let mut scope = ROOT_SCOPE_ID;
            for ancestor in node_id.ancestors(tree).skip(1) {
                if let Some(registration) = tree[ancestor].get().interaction().focus_registration {
                    if parent == ROOT_SCOPE_ID {
                        parent = registration.id;
                    }
                    if registration.kind == FocusRegistrationKind::Scope {
                        scope = registration.id;
                        break;
                    }
                }
            }
            let entry = self
                .nodes
                .entry(registration.id)
                .or_insert_with(|| FocusTreeNode::new(registration.kind));
            entry.kind = registration.kind;
            entry.last_parent = parent;
            entry.last_scope_parent = scope;
            entry.props = registration.properties;
            entry.traversal_policy = interaction.focus_traversal_policy;
            entry.restorer_fallback = (registration.kind == FocusRegistrationKind::Scope)
                .then(|| {
                    interaction
                        .focus_restorer_fallback
                        .map(|fallback| fallback.requester_id())
                })
                .flatten();
            entry.attachment = Some(FocusAttachment {
                host_replay_boundary_key: nearest_replay_boundary_instance_key(node_id, tree),
                live_node_id: Some(node_id),
                focus_rect: None,
                traversal_order: None,
                parent,
                scope_parent: scope,
            });
            self.handles_by_component.insert(node_id, registration.id);
            let order: Vec<_> = node_id
                .ancestors(tree)
                .filter(|id| tree[*id].parent().is_some())
                .map(|id| (u64::MAX, sibling_index(id, tree)))
                .collect::<Vec<_>>()
                .into_iter()
                .rev()
                .collect();
            self.order_paths.insert(registration.id, order.clone());
            self.children_by_parent
                .entry(parent)
                .or_default()
                .insert((order, registration.id), registration.id);
            self.children_by_parent.entry(registration.id).or_default();
            if let Some(requester) = interaction.focus_requester_binding {
                let requester = requester.requester_id();
                let previous = self.requester_bindings.insert(requester, registration.id);
                requesters.entry(requester).or_insert(previous);
                self.requesters_by_handle
                    .entry(registration.id)
                    .or_default()
                    .push(requester);
            }
        }
        self.repair_after_sync();
        self.recompute_states();
        self.notify_state_changes(previous_states);
        for (requester, previous) in requesters {
            if self.requester_bindings.get(&requester).copied() == previous {
                continue;
            }
            for reader in focus_requester_read_subscribers(requester) {
                record_replay_boundary_invalidation_for_instance_key(reader);
            }
        }
    }

    pub(crate) fn sync_geometry_changes(
        &mut self,
        tree: &ComponentNodeTree,
        metadatas: &ComponentNodeMetaDatas,
        geometry_changed: &HashSet<NodeId>,
        structure_changed: &HashSet<NodeId>,
    ) {
        if (geometry_changed.is_empty() && structure_changed.is_empty())
            || (self.handles_by_component.is_empty() && self.active.is_none())
        {
            return;
        }
        for node_id in geometry_changed.union(structure_changed) {
            let Some(&handle) = self.handles_by_component.get(node_id) else {
                continue;
            };
            let rect = metadatas.get(node_id).and_then(|metadata| {
                let position = metadata.abs_position?;
                let size = metadata.computed_data?;
                let transform = metadata
                    .local_to_window
                    .unwrap_or_else(|| crate::LocalToWindow::new(1.0, position).unwrap());
                let rect = transform
                    .map_rect(crate::FloatRect::from_position_size(
                        PxPosition::ZERO,
                        PxSize::new(size.width, size.height),
                    ))
                    .outward();
                Some(metadata.event_clip_rect().map_or(rect, |clip| {
                    clip.intersection(&rect).unwrap_or(PxRect::ZERO)
                }))
            });
            if let Some(attachment) = self
                .nodes
                .get_mut(&handle)
                .and_then(|node| node.attachment.as_mut())
            {
                attachment.focus_rect = rect;
                if attachment.traversal_order.is_some()
                    && !metadatas.placement_order_changed.contains(node_id)
                {
                    continue;
                }
            }
            let mut order = node_id
                .ancestors(tree)
                .filter_map(|id| {
                    let node = tree.get(id)?;
                    node.parent()?;
                    if node.get().role != NodeRole::Layout
                        && node.get().interaction().focus_registration.is_none()
                    {
                        return None;
                    }
                    Some((
                        metadatas
                            .get(&id)
                            .and_then(|metadata| metadata.placement_order)
                            .unwrap_or(u64::MAX),
                        sibling_index(id, tree),
                    ))
                })
                .collect::<Vec<_>>();
            order.reverse();
            let order_changed = self.order_paths.get(&handle) != Some(&order);
            if let Some(attachment) = self
                .nodes
                .get_mut(&handle)
                .and_then(|node| node.attachment.as_mut())
            {
                attachment.focus_rect = rect;
                attachment.traversal_order = Some(0);
                if !order_changed {
                    continue;
                }
                let previous_order = self.order_paths.insert(handle, order.clone());
                let children = self
                    .children_by_parent
                    .entry(attachment.parent)
                    .or_default();
                if let Some(previous) = previous_order {
                    children.remove(&(previous, handle));
                }
                children.insert((order, handle), handle);
            }
        }
        if self.active.is_some_and(|id| {
            self.nodes.get(&id).is_some_and(|node| node.is_attached())
                && !self.can_request_focus(id)
        }) {
            let previous_states = self.snapshot_live_states();
            self.active = self
                .active
                .and_then(|id| self.restore_single_tab_stop_group(id));
            self.captured = None;
            self.pending_reveal = self.active;
            if let Some(active) = self.active {
                self.update_scope_restore_chain(active);
            }
            self.recompute_states();
            self.notify_state_changes(previous_states);
        }
    }

    #[cfg(test)]
    pub(crate) fn sync_from_component_tree(&mut self, root_node: NodeId, tree: &ComponentNodeTree) {
        let changed = root_node.descendants(tree).collect::<HashSet<_>>();
        let removed = self
            .handles_by_component
            .keys()
            .copied()
            .filter(|node| !changed.contains(node))
            .collect();
        self.sync_changes(tree, &changed, &removed);
    }

    #[cfg(test)]
    pub(crate) fn sync_layout_from_component_tree(
        &mut self,
        tree: &ComponentNodeTree,
        metadatas: &ComponentNodeMetaDatas,
    ) {
        let changed = self.handles_by_component.keys().copied().collect();
        self.sync_geometry_changes(tree, metadatas, &changed, &HashSet::default());
    }

    pub(crate) fn commit_pending(&mut self) {
        if self.pending.is_empty() {
            return;
        }

        let previous_states = self.snapshot_live_states();
        let commands = std::mem::take(&mut self.pending);
        for pending in commands {
            let reveal = self.pending_reveal;
            let applied = self.apply_command_inner(pending.command);
            if !pending.reveal {
                self.pending_reveal = reveal;
            }
            if !applied && self.should_defer_command(pending.command) {
                self.pending.push(pending);
            }
        }
        self.recompute_states();
        self.notify_state_changes(previous_states);
    }

    pub(crate) fn take_pending_notifications(&mut self) -> Vec<FocusNotification> {
        std::mem::take(&mut self.pending_notifications)
    }

    pub(crate) fn clear_focus_global(&mut self, force: bool) -> bool {
        if force || self.captured.is_none() {
            self.pending_navigation = None;
        }
        let previous_states = self.snapshot_live_states();
        let cleared = if self.active.is_some() && (force || self.captured.is_none()) {
            self.active = None;
            self.captured = None;
            self.pending_reveal = None;
            true
        } else {
            false
        };
        self.recompute_states();
        self.notify_state_changes(previous_states);
        cleared
    }

    pub(crate) fn move_focus(&mut self, direction: FocusDirection) -> bool {
        if !self.owner_focused {
            return false;
        }
        let previous_states = self.snapshot_live_states();
        let target = match self.resolve_policy_move_target(direction) {
            Some(target) => target,
            None => self.resolve_move_target(direction),
        };
        let moved = target.is_some_and(|target| self.set_active(target));
        self.recompute_states();
        self.notify_state_changes_from(previous_states, Some(direction));
        moved
    }

    pub(crate) fn move_focus_in_scope(
        &mut self,
        scope_id: FocusHandleId,
        direction: FocusDirection,
        wrap: bool,
    ) -> bool {
        if !self.owner_focused {
            return false;
        }
        let previous_states = self.snapshot_live_states();
        let moved = self
            .resolve_move_target_in_scope(scope_id, direction, wrap)
            .is_some_and(|target| self.set_active(target));
        self.recompute_states();
        self.notify_state_changes_from(previous_states, Some(direction));
        moved
    }

    fn resolve_policy_move_target(
        &self,
        direction: FocusDirection,
    ) -> Option<Option<FocusHandleId>> {
        let active = self
            .active
            .filter(|current| self.can_request_focus(*current))?;
        let (owner_id, policy) = self.nearest_traversal_policy_owner(active)?;
        let scoped_direction = policy.scoped_direction(direction)?;
        let target = self.resolve_move_target_in_scope(owner_id, scoped_direction, policy.wrap);
        // Empty wrapping scopes still own traversal; an absent candidate must
        // not be interpreted as permission to navigate behind a modal.
        (target.is_some() || policy.wrap).then_some(target)
    }

    fn nearest_traversal_policy_owner(
        &self,
        start: FocusHandleId,
    ) -> Option<(FocusHandleId, FocusTraversalPolicy)> {
        let mut current = Some(start);
        while let Some(id) = current {
            let node = self.nodes.get(&id)?;
            if matches!(
                node.kind,
                FocusRegistrationKind::Scope | FocusRegistrationKind::Group
            ) && let Some(policy) = node.traversal_policy
            {
                return Some((id, policy));
            }
            current = (id != ROOT_SCOPE_ID).then_some(node.last_parent);
        }
        None
    }

    fn repair_after_sync(&mut self) {
        if self
            .active
            .is_some_and(|id| !self.nodes.get(&id).is_some_and(|node| node.is_attached()))
        {
            let previous_active = self.active;
            if previous_active
                .and_then(|id| self.restore_single_tab_stop_group(id))
                .is_some()
                || !previous_active.is_some_and(|id| self.should_wait_for_reattach(id))
            {
                let previous_active = self.active.take();
                self.active = previous_active.and_then(|id| self.restore_from_detached(id));
                self.captured = None;
                if let Some(active) = self.active {
                    self.update_scope_restore_chain(active);
                    self.pending_reveal = Some(active);
                }
            }
        }

        if self
            .captured
            .is_some_and(|id| !self.nodes.get(&id).is_some_and(|node| node.is_attached()))
        {
            self.captured = None;
        }

        if self.owner_focused
            && self.active.is_none()
            && let Some(suspended) = self.suspended
            && let Some(target) = self.resolve_request_target(suspended)
        {
            self.active = Some(target);
            self.suspended = None;
            self.pending_reveal = Some(target);
        }

        if self.active.is_some_and(|id| {
            self.nodes.get(&id).is_some_and(|node| {
                node.is_attached() && (!self.can_focus(id) || !self.can_request_focus(id))
            })
        }) {
            self.active = self
                .active
                .and_then(|id| self.restore_single_tab_stop_group(id));
            self.captured = None;
            self.pending_reveal = self.active;
            if let Some(active) = self.active {
                self.update_scope_restore_chain(active);
            }
        }
    }

    fn should_wait_for_reattach(&self, id: FocusHandleId) -> bool {
        let Some(node) = self.nodes.get(&id) else {
            return false;
        };
        if node.is_attached() {
            return false;
        }
        if has_persistent_focus_handle(id) {
            return true;
        }
        let waiting_scope_id = node.last_scope_parent;
        waiting_scope_id != ROOT_SCOPE_ID
            && self
                .nodes
                .get(&waiting_scope_id)
                .is_some_and(|scope| !scope.is_attached())
    }

    pub(crate) fn remove_handles(
        &mut self,
        removed_handles: &HashSet<FocusHandleId>,
        removed_requesters: &HashSet<FocusRequesterId>,
    ) {
        if removed_handles.is_empty() && removed_requesters.is_empty() {
            return;
        }

        let previous_states = self.snapshot_live_states();
        let mut previous_requester_bindings = HashMap::default();
        for requester_id in removed_requesters {
            if let Some(handle) = self.requester_bindings.remove(requester_id) {
                previous_requester_bindings.insert(*requester_id, handle);
                if let Some(requesters) = self.requesters_by_handle.get_mut(&handle) {
                    requesters.retain(|id| id != requester_id);
                }
            }
        }
        // Restore against survivors while retaining scope ancestry until
        // cleanup finishes.
        for handle_id in removed_handles {
            if let Some(node) = self.nodes.get_mut(handle_id) {
                node.attachment = None;
            }
        }

        let active_was_removed = self.active.filter(|id| removed_handles.contains(id));
        if active_was_removed.is_some() {
            self.active = active_was_removed.and_then(|id| self.restore_from_detached(id));
            self.captured = None;
            if let Some(active) = self.active {
                self.update_scope_restore_chain(active);
                self.pending_reveal = Some(active);
            } else {
                self.pending_reveal = None;
            }
        }

        if self
            .captured
            .is_some_and(|id| removed_handles.contains(&id))
        {
            self.captured = None;
        }
        if self
            .suspended
            .is_some_and(|id| removed_handles.contains(&id))
        {
            self.suspended = None;
        }

        for handle_id in removed_handles {
            if let Some(node) = self.nodes.remove(handle_id) {
                if let Some(children) = self.children_by_parent.get_mut(&node.last_parent) {
                    if let Some(order) = self.order_paths.get(handle_id) {
                        children.remove(&(order.clone(), *handle_id));
                    }
                }
            }
            self.children_by_parent.remove(handle_id);
            self.stateful_handles.remove(handle_id);
            self.order_paths.remove(handle_id);
            if let Some(requesters) = self.requesters_by_handle.remove(handle_id) {
                for requester in requesters {
                    if let Some(handle) = self.requester_bindings.remove(&requester) {
                        previous_requester_bindings.insert(requester, handle);
                    }
                }
            }
        }

        self.recompute_states();
        self.notify_state_changes(previous_states);
        self.notify_requester_binding_changes(previous_requester_bindings);
    }

    fn execute_or_defer(&mut self, command: FocusCommand) {
        self.pending_navigation = None;
        if matches!(command, FocusCommand::Request(_) | FocusCommand::Restore(_)) {
            self.discard_pending_focus_requests();
        }
        if !self.apply_command(command) && self.should_defer_command(command) {
            self.pending.push(DeferredFocusCommand {
                command,
                reveal: true,
            });
        }
    }

    fn discard_pending_focus_requests(&mut self) {
        self.pending.retain(|pending| {
            !matches!(
                pending.command,
                FocusCommand::Request(_) | FocusCommand::Restore(_)
            )
        });
    }

    fn should_defer_command(&self, command: FocusCommand) -> bool {
        let id = match command {
            FocusCommand::Request(id)
            | FocusCommand::Clear(id)
            | FocusCommand::Capture(id)
            | FocusCommand::Free(id)
            | FocusCommand::Restore(id) => id,
        };
        // Attached targets treat commands as immediate intents. Replaying a
        // no-op or rejected command after another event can steal or clear
        // focus.
        !self.nodes.get(&id).is_some_and(|node| node.is_attached())
    }

    fn apply_command(&mut self, command: FocusCommand) -> bool {
        let previous_states = self.snapshot_live_states();
        let applied = self.apply_command_inner(command);
        self.recompute_states();
        self.notify_state_changes(previous_states);
        applied
    }

    fn apply_command_inner(&mut self, command: FocusCommand) -> bool {
        match command {
            FocusCommand::Request(id) => {
                if !self.owner_focused {
                    self.suspended = Some(id);
                    return true;
                }
                let Some(target) = self.resolve_request_target(id) else {
                    return false;
                };
                self.set_active(target)
            }
            FocusCommand::Clear(id) => self.clear_active_for(id),
            FocusCommand::Capture(id) => {
                if self.active == Some(id)
                    && self.nodes.get(&id).is_some_and(|node| node.is_attached())
                {
                    self.captured = Some(id);
                    true
                } else {
                    false
                }
            }
            FocusCommand::Free(id) => {
                if self.captured == Some(id) {
                    self.captured = None;
                    true
                } else {
                    false
                }
            }
            FocusCommand::Restore(id) => {
                let Some(target) = self.resolve_restore_candidate(id) else {
                    return false;
                };
                self.set_active(target)
            }
        }
    }

    fn set_active(&mut self, target: FocusHandleId) -> bool {
        if self.captured.is_some() && self.captured != Some(target) {
            return false;
        }
        self.discard_pending_focus_requests();
        let changed = self.active != Some(target) || self.captured.is_some_and(|id| id != target);
        self.active = Some(target);
        if self.captured.is_some_and(|id| id != target) {
            self.captured = None;
        }
        self.update_scope_restore_chain(target);
        if changed {
            self.pending_reveal = Some(target);
        }
        changed
    }

    fn clear_active_for(&mut self, id: FocusHandleId) -> bool {
        let Some(active) = self.active else {
            return false;
        };
        let affects_active = active == id || self.is_ancestor(id, active);
        if !affects_active {
            return false;
        }
        if self.captured.is_some() {
            return false;
        }

        self.active = None;
        self.captured = None;
        self.pending_reveal = None;
        true
    }

    fn resolve_move_target(&self, direction: FocusDirection) -> Option<FocusHandleId> {
        if let Some(active) = self.active
            && let Some(explicit) = self.resolve_explicit_direction_target(active, direction)
        {
            return Some(explicit);
        }

        if matches!(
            direction,
            FocusDirection::Left
                | FocusDirection::Right
                | FocusDirection::Up
                | FocusDirection::Down
        ) && let Some(target) = self.resolve_geometric_move_target(direction)
        {
            return Some(target);
        }

        let candidates = if matches!(direction, FocusDirection::Next | FocusDirection::Previous) {
            let mut candidates = Vec::new();
            self.collect_tab_focus_handles(ROOT_SCOPE_ID, &mut candidates);
            candidates
        } else {
            self.traversable_focus_handles()
        };
        if candidates.is_empty() {
            return None;
        }

        let forward = matches!(
            direction,
            FocusDirection::Next
                | FocusDirection::Down
                | FocusDirection::Right
                | FocusDirection::Enter
        );

        let Some(active) = self
            .active
            .filter(|current| self.can_request_focus(*current))
        else {
            return if forward {
                candidates.first().copied()
            } else {
                candidates.last().copied()
            };
        };

        let Some(index) = candidates.iter().position(|candidate| *candidate == active) else {
            return if forward {
                candidates.first().copied()
            } else {
                candidates.last().copied()
            };
        };

        if forward {
            candidates.get(index + 1).copied()
        } else if index > 0 {
            candidates.get(index - 1).copied()
        } else {
            None
        }
    }

    fn resolve_move_target_in_scope(
        &self,
        scope_id: FocusHandleId,
        direction: FocusDirection,
        wrap: bool,
    ) -> Option<FocusHandleId> {
        let candidates = self.traversable_focus_handles_in_scope(scope_id);
        if candidates.is_empty() {
            return None;
        }

        let active = self
            .active
            .filter(|current| self.can_request_focus(*current))
            .filter(|current| self.is_ancestor(scope_id, *current));

        if let Some(active) = active
            && let Some(explicit) = self.resolve_explicit_direction_target(active, direction)
            && self.is_ancestor(scope_id, explicit)
        {
            return Some(explicit);
        }

        if matches!(
            direction,
            FocusDirection::Left
                | FocusDirection::Right
                | FocusDirection::Up
                | FocusDirection::Down
        ) && let Some(target) =
            self.resolve_geometric_move_target_in_candidates(direction, &candidates, active)
        {
            return Some(target);
        }

        let forward = matches!(
            direction,
            FocusDirection::Next
                | FocusDirection::Down
                | FocusDirection::Right
                | FocusDirection::Enter
        );

        let Some(active) = active else {
            return if forward {
                candidates.first().copied()
            } else {
                candidates.last().copied()
            };
        };

        let Some(index) = candidates.iter().position(|candidate| *candidate == active) else {
            return if forward {
                candidates.first().copied()
            } else {
                candidates.last().copied()
            };
        };

        if forward {
            candidates.get(index + 1).copied().or_else(|| {
                wrap.then_some(candidates.first().copied())
                    .flatten()
                    .filter(|candidate| self.is_traversable_focus_handle(*candidate))
            })
        } else if index > 0 {
            candidates.get(index - 1).copied()
        } else if wrap {
            candidates
                .last()
                .copied()
                .filter(|candidate| self.is_traversable_focus_handle(*candidate))
        } else {
            None
        }
    }

    fn resolve_geometric_move_target(&self, direction: FocusDirection) -> Option<FocusHandleId> {
        let active = self.active.and_then(|id| self.resolve_request_target(id))?;
        let focused_rect = self.nodes.get(&active)?.attachment?.focus_rect?;
        let mut best_candidate = initial_best_candidate_rect(focused_rect, direction);
        let mut best_handle = None;

        for handle_id in self.traversable_focus_handles() {
            if handle_id == active {
                continue;
            }
            let Some(candidate_rect) = self
                .nodes
                .get(&handle_id)
                .and_then(|node| node.attachment)
                .and_then(|attachment| attachment.focus_rect)
            else {
                continue;
            };
            if !is_eligible_focus_rect(candidate_rect) {
                continue;
            }
            if is_better_focus_candidate(candidate_rect, best_candidate, focused_rect, direction) {
                best_candidate = candidate_rect;
                best_handle = Some(handle_id);
            }
        }

        best_handle
    }

    fn resolve_geometric_move_target_in_candidates(
        &self,
        direction: FocusDirection,
        candidates: &[FocusHandleId],
        active: Option<FocusHandleId>,
    ) -> Option<FocusHandleId> {
        let active = active?;
        let focused_rect = self.nodes.get(&active)?.attachment?.focus_rect?;
        let mut best_candidate = initial_best_candidate_rect(focused_rect, direction);
        let mut best_handle = None;

        for &handle_id in candidates {
            if handle_id == active {
                continue;
            }
            let Some(candidate_rect) = self
                .nodes
                .get(&handle_id)
                .and_then(|node| node.attachment)
                .and_then(|attachment| attachment.focus_rect)
            else {
                continue;
            };
            if !is_eligible_focus_rect(candidate_rect) {
                continue;
            }
            if is_better_focus_candidate(candidate_rect, best_candidate, focused_rect, direction) {
                best_candidate = candidate_rect;
                best_handle = Some(handle_id);
            }
        }

        best_handle
    }

    fn resolve_request_target(&self, id: FocusHandleId) -> Option<FocusHandleId> {
        let node = self.nodes.get(&id)?;
        if !node.is_attached() {
            return None;
        }
        match node.kind {
            FocusRegistrationKind::Target => self.can_request_focus(id).then_some(id),
            FocusRegistrationKind::Scope => self
                .resolve_restore_candidate(id)
                .or_else(|| self.first_focusable_descendant(id))
                .or_else(|| self.can_request_focus(id).then_some(id)),
            FocusRegistrationKind::Group => self
                .first_focusable_descendant(id)
                .or_else(|| self.can_request_focus(id).then_some(id)),
        }
    }

    fn resolve_requester_target(&self, requester_id: FocusRequesterId) -> Option<FocusHandleId> {
        self.requester_bindings.get(&requester_id).copied()
    }

    fn resolve_explicit_direction_target(
        &self,
        id: FocusHandleId,
        direction: FocusDirection,
    ) -> Option<FocusHandleId> {
        let requester = self.nodes.get(&id).and_then(|node| match direction {
            FocusDirection::Next => node.props.next,
            FocusDirection::Previous => node.props.previous,
            FocusDirection::Up => node.props.up,
            FocusDirection::Down => node.props.down,
            FocusDirection::Left => node.props.left,
            FocusDirection::Right => node.props.right,
            FocusDirection::Enter => node.props.enter,
            FocusDirection::Exit => node.props.exit,
        })?;
        let handle_id = self.resolve_requester_target(requester.requester_id())?;
        self.resolve_request_target(handle_id)
    }

    fn resolve_restore_candidate(&self, id: FocusHandleId) -> Option<FocusHandleId> {
        let scope = self.nodes.get(&id)?;
        if !scope.is_attached() || scope.kind != FocusRegistrationKind::Scope {
            return None;
        }
        scope
            .last_focused_descendant
            .filter(|candidate| *candidate != id && self.can_request_focus(*candidate))
            .or_else(|| {
                scope
                    .restorer_fallback
                    .and_then(|requester_id| self.resolve_requester_target(requester_id))
                    .and_then(|candidate| self.resolve_request_target(candidate))
            })
            .or_else(|| self.first_focusable_descendant(id))
    }

    fn traversable_focus_handles(&self) -> Vec<FocusHandleId> {
        let mut ordered = Vec::new();
        self.collect_traversable_focus_handles(ROOT_SCOPE_ID, &mut ordered);
        ordered
    }

    fn collect_tab_focus_handles(&self, parent: FocusHandleId, ordered: &mut Vec<FocusHandleId>) {
        let Some(children) = self.children_by_parent.get(&parent) else {
            return;
        };
        for &child in children.values() {
            if self.is_single_tab_stop_group(child) {
                let target = self
                    .active
                    .filter(|active| {
                        self.is_ancestor(child, *active) && self.can_request_focus(*active)
                    })
                    .or_else(|| self.tab_entry_target(child));
                if let Some(target) = target {
                    ordered.push(target);
                }
                continue;
            }
            if self.is_traversable_focus_handle(child)
                || (self.active == Some(child) && self.can_request_focus(child))
            {
                ordered.push(child);
            }
            self.collect_tab_focus_handles(child, ordered);
        }
    }

    fn is_single_tab_stop_group(&self, id: FocusHandleId) -> bool {
        self.nodes.get(&id).is_some_and(|node| {
            node.is_attached()
                && matches!(
                    node.kind,
                    FocusRegistrationKind::Group | FocusRegistrationKind::Scope
                )
                && node
                    .traversal_policy
                    .is_some_and(|policy| policy.single_tab_stop)
        })
    }

    fn tab_entry_target(&self, group: FocusHandleId) -> Option<FocusHandleId> {
        let mut candidates = Vec::new();
        self.collect_tab_focus_handles(group, &mut candidates);
        candidates
            .iter()
            .copied()
            .find(|id| {
                self.is_traversable_focus_handle(*id)
                    && self
                        .nodes
                        .get(id)
                        .is_some_and(|node| node.props.preferred_tab_stop)
            })
            .or_else(|| {
                candidates
                    .into_iter()
                    .find(|id| self.is_traversable_focus_handle(*id))
            })
    }

    fn restore_single_tab_stop_group(&self, id: FocusHandleId) -> Option<FocusHandleId> {
        let mut current = self.nodes.get(&id).map(|node| node.last_parent);
        while let Some(parent) = current {
            if self.is_single_tab_stop_group(parent) {
                return self.tab_entry_target(parent);
            }
            current = self
                .nodes
                .get(&parent)
                .and_then(|node| (parent != ROOT_SCOPE_ID).then_some(node.last_parent));
        }
        None
    }

    fn traversable_focus_handles_in_scope(&self, scope_id: FocusHandleId) -> Vec<FocusHandleId> {
        let mut ordered = Vec::new();
        self.collect_traversable_focus_handles(scope_id, &mut ordered);
        ordered
    }

    fn collect_traversable_focus_handles(
        &self,
        parent: FocusHandleId,
        ordered: &mut Vec<FocusHandleId>,
    ) {
        let Some(children) = self.children_by_parent.get(&parent) else {
            return;
        };
        for &child in children.values() {
            // A skipped target can hold focus and must retain its position as a
            // traversal anchor.
            if self.is_traversable_focus_handle(child)
                || (self.active == Some(child) && self.can_request_focus(child))
            {
                ordered.push(child);
            }
            self.collect_traversable_focus_handles(child, ordered);
        }
    }

    fn is_traversable_focus_handle(&self, id: FocusHandleId) -> bool {
        self.can_request_focus(id)
            && self
                .nodes
                .get(&id)
                .is_some_and(|node| !node.props.skip_traversal)
    }

    fn first_focusable_descendant(&self, parent: FocusHandleId) -> Option<FocusHandleId> {
        let mut stack: Vec<_> = self
            .children_by_parent
            .get(&parent)
            .into_iter()
            .flat_map(|children| children.values().rev())
            .copied()
            .collect();
        while let Some(id) = stack.pop() {
            if self.can_request_focus(id) {
                return Some(id);
            }
            if let Some(children) = self.children_by_parent.get(&id) {
                stack.extend(children.values().rev().copied());
            }
        }
        None
    }

    fn restore_from_detached(&self, id: FocusHandleId) -> Option<FocusHandleId> {
        if let Some(target) = self.restore_single_tab_stop_group(id) {
            return Some(target);
        }
        let mut current_scope = self.nodes.get(&id).map(|node| node.last_scope_parent)?;
        loop {
            if current_scope == ROOT_SCOPE_ID {
                break;
            }
            if let Some(candidate) = self.resolve_restore_candidate(current_scope) {
                return Some(candidate);
            }
            current_scope = self
                .nodes
                .get(&current_scope)
                .map(|node| node.last_scope_parent)
                .unwrap_or(ROOT_SCOPE_ID);
        }
        None
    }

    fn update_scope_restore_chain(&mut self, target: FocusHandleId) {
        let mut current = Some(target);
        while let Some(id) = current {
            if let Some(node) = self.nodes.get_mut(&id)
                && node.kind == FocusRegistrationKind::Scope
            {
                node.last_focused_descendant = Some(target);
            }
            if id == ROOT_SCOPE_ID {
                break;
            }
            current = self
                .nodes
                .get(&id)
                .and_then(|node| node.attachment)
                .map(|attachment| attachment.scope_parent);
            if current == Some(id) {
                break;
            }
        }
        if let Some(root) = self.nodes.get_mut(&ROOT_SCOPE_ID) {
            root.last_focused_descendant = Some(target);
        }
    }

    fn snapshot_live_states(&self) -> HashMap<FocusHandleId, FocusState> {
        self.stateful_handles
            .iter()
            .filter_map(|&id| {
                self.nodes
                    .get(&id)
                    .filter(|node| node.is_attached())
                    .map(|node| (id, node.state))
            })
            .collect()
    }

    fn notify_requester_binding_changes(
        &self,
        previous_bindings: HashMap<FocusRequesterId, FocusHandleId>,
    ) {
        let mut changed = HashSet::default();
        for (&requester_id, &previous_handle_id) in &previous_bindings {
            let current = self.requester_bindings.get(&requester_id).copied();
            if current != Some(previous_handle_id) {
                changed.insert(requester_id);
            }
        }
        for requester_id in changed {
            for reader in focus_requester_read_subscribers(requester_id) {
                record_replay_boundary_invalidation_for_instance_key(reader);
            }
        }
    }

    fn notify_state_changes(&mut self, previous_states: HashMap<FocusHandleId, FocusState>) {
        self.notify_state_changes_from(previous_states, None);
    }

    fn notify_state_changes_from(
        &mut self,
        previous_states: HashMap<FocusHandleId, FocusState>,
        direction: Option<FocusDirection>,
    ) {
        let mut changed = HashSet::default();
        let mut events = HashSet::default();
        let mut changed_requesters = HashSet::default();

        for (&id, &previous) in &previous_states {
            let current = self
                .nodes
                .get(&id)
                .filter(|node| node.is_attached())
                .map(|node| node.state)
                .unwrap_or(FocusState::Inactive);
            if previous != current {
                changed.insert(id);
            }
            if previous.has_focus() {
                events.insert(id);
            }
        }

        for &id in &self.stateful_handles {
            let Some(node) = self.nodes.get(&id) else {
                continue;
            };
            if !node.is_attached() {
                continue;
            }
            let previous = previous_states
                .get(&id)
                .copied()
                .unwrap_or(FocusState::Inactive);
            if previous != node.state {
                changed.insert(id);
            }
            if node.state.has_focus() {
                events.insert(id);
            }
        }

        for &id in &changed {
            let state = self
                .nodes
                .get(&id)
                .filter(|node| node.is_attached())
                .map(|node| node.state)
                .unwrap_or(FocusState::Inactive);
            self.pending_notifications.push(FocusNotification {
                handle_id: id,
                state,
                changed: true,
                direction,
            });
            for reader in focus_read_subscribers(id) {
                record_replay_boundary_invalidation_for_instance_key(reader);
            }
            if let Some(node) = self.nodes.get(&id)
                && let Some(attachment) = node.attachment
                && attachment.host_replay_boundary_key != 0
            {
                record_replay_boundary_invalidation_for_instance_key(
                    attachment.host_replay_boundary_key,
                );
            }
            if let Some(requesters) = self.requesters_by_handle.get(&id) {
                changed_requesters.extend(requesters.iter().copied());
            }
        }

        for id in events {
            if changed.contains(&id) {
                continue;
            }
            let state = self
                .nodes
                .get(&id)
                .filter(|node| node.is_attached())
                .map(|node| node.state)
                .unwrap_or(FocusState::Inactive);
            self.pending_notifications.push(FocusNotification {
                handle_id: id,
                state,
                changed: false,
                direction,
            });
        }

        for requester_id in changed_requesters {
            for reader in focus_requester_read_subscribers(requester_id) {
                record_replay_boundary_invalidation_for_instance_key(reader);
            }
        }
    }

    fn recompute_states(&mut self) {
        for id in self.stateful_handles.drain() {
            if let Some(node) = self.nodes.get_mut(&id) {
                node.state = FocusState::Inactive;
            }
        }
        let Some(active) = self.active else {
            return;
        };
        if !self
            .nodes
            .get(&active)
            .is_some_and(|node| node.is_attached())
        {
            return;
        }

        let mut current = Some(active);
        let active_state = if self.captured == Some(active) {
            FocusState::Captured
        } else {
            FocusState::Active
        };
        let mut first = true;
        while let Some(id) = current {
            if let Some(node) = self.nodes.get_mut(&id)
                && node.is_attached()
            {
                self.stateful_handles.insert(id);
                node.state = if first {
                    active_state
                } else {
                    FocusState::ActiveParent
                };
            }
            if id == ROOT_SCOPE_ID {
                break;
            }
            current = self
                .nodes
                .get(&id)
                .and_then(|node| node.attachment)
                .map(|attachment| attachment.parent);
            first = false;
        }
    }

    fn can_focus(&self, id: FocusHandleId) -> bool {
        self.nodes.get(&id).is_some_and(|node| {
            node.attachment.is_some_and(FocusAttachment::permits_focus) && node.props.can_focus
        })
    }

    fn can_request_focus(&self, id: FocusHandleId) -> bool {
        self.can_focus(id)
            && self
                .nodes
                .get(&id)
                .is_some_and(|node| node.props.can_request_focus)
    }

    fn is_ancestor(&self, ancestor: FocusHandleId, descendant: FocusHandleId) -> bool {
        let mut current = Some(descendant);
        while let Some(id) = current {
            if id == ancestor {
                return true;
            }
            if id == ROOT_SCOPE_ID {
                break;
            }
            current = self
                .nodes
                .get(&id)
                .and_then(|node| node.attachment)
                .map(|attachment| attachment.parent);
        }
        false
    }
}

fn is_eligible_focus_rect(rect: PxRect) -> bool {
    rect.width.0 > 0 && rect.height.0 > 0
}

fn initial_best_candidate_rect(focused_rect: PxRect, direction: FocusDirection) -> PxRect {
    match direction {
        FocusDirection::Left => PxRect::new(
            focused_rect.x + focused_rect.width + crate::Px::new(1),
            focused_rect.y,
            focused_rect.width,
            focused_rect.height,
        ),
        FocusDirection::Right => PxRect::new(
            focused_rect.x - focused_rect.width - crate::Px::new(1),
            focused_rect.y,
            focused_rect.width,
            focused_rect.height,
        ),
        FocusDirection::Up => PxRect::new(
            focused_rect.x,
            focused_rect.y + focused_rect.height + crate::Px::new(1),
            focused_rect.width,
            focused_rect.height,
        ),
        FocusDirection::Down => PxRect::new(
            focused_rect.x,
            focused_rect.y - focused_rect.height - crate::Px::new(1),
            focused_rect.width,
            focused_rect.height,
        ),
        _ => focused_rect,
    }
}

fn is_better_focus_candidate(
    proposed_candidate: PxRect,
    current_candidate: PxRect,
    focused_rect: PxRect,
    direction: FocusDirection,
) -> bool {
    if !is_focus_candidate(proposed_candidate, focused_rect, direction) {
        return false;
    }
    if !is_focus_candidate(current_candidate, focused_rect, direction) {
        return true;
    }
    if focus_beam_beats(
        focused_rect,
        proposed_candidate,
        current_candidate,
        direction,
    ) {
        return true;
    }
    if focus_beam_beats(
        focused_rect,
        current_candidate,
        proposed_candidate,
        direction,
    ) {
        return false;
    }
    weighted_focus_distance(proposed_candidate, focused_rect, direction)
        < weighted_focus_distance(current_candidate, focused_rect, direction)
}

fn is_focus_candidate(rect: PxRect, focused_rect: PxRect, direction: FocusDirection) -> bool {
    match direction {
        FocusDirection::Left => {
            (focused_rect_right(focused_rect) > focused_rect_right(rect)
                || focused_rect.x >= focused_rect_right(rect))
                && focused_rect.x > rect.x
        }
        FocusDirection::Right => {
            (focused_rect.x < rect.x || focused_rect_right(focused_rect) <= rect.x)
                && focused_rect_right(focused_rect) < focused_rect_right(rect)
        }
        FocusDirection::Up => {
            (focused_rect_bottom(focused_rect) > focused_rect_bottom(rect)
                || focused_rect.y >= focused_rect_bottom(rect))
                && focused_rect.y > rect.y
        }
        FocusDirection::Down => {
            (focused_rect.y < rect.y || focused_rect_bottom(focused_rect) <= rect.y)
                && focused_rect_bottom(focused_rect) < focused_rect_bottom(rect)
        }
        _ => false,
    }
}

fn weighted_focus_distance(rect: PxRect, focused_rect: PxRect, direction: FocusDirection) -> i64 {
    let major = major_axis_distance(rect, focused_rect, direction);
    let minor = minor_axis_distance(rect, focused_rect, direction);
    13 * major * major + minor * minor
}

fn focus_beam_beats(
    source: PxRect,
    rect1: PxRect,
    rect2: PxRect,
    direction: FocusDirection,
) -> bool {
    if rect2_in_source_beam(rect2, source, direction)
        || !rect2_in_source_beam(rect1, source, direction)
    {
        return false;
    }
    if !is_in_direction_of_search(rect2, source, direction) {
        return true;
    }
    if matches!(direction, FocusDirection::Left | FocusDirection::Right) {
        return true;
    }
    major_axis_distance(rect1, source, direction)
        < major_axis_distance_to_far_edge(rect2, source, direction)
}

fn rect2_in_source_beam(rect: PxRect, source: PxRect, direction: FocusDirection) -> bool {
    match direction {
        FocusDirection::Left | FocusDirection::Right => {
            focused_rect_bottom(rect) > source.y && rect.y < focused_rect_bottom(source)
        }
        FocusDirection::Up | FocusDirection::Down => {
            focused_rect_right(rect) > source.x && rect.x < focused_rect_right(source)
        }
        _ => false,
    }
}

fn is_in_direction_of_search(rect: PxRect, source: PxRect, direction: FocusDirection) -> bool {
    match direction {
        FocusDirection::Left => source.x >= focused_rect_right(rect),
        FocusDirection::Right => focused_rect_right(source) <= rect.x,
        FocusDirection::Up => source.y >= focused_rect_bottom(rect),
        FocusDirection::Down => focused_rect_bottom(source) <= rect.y,
        _ => false,
    }
}

fn major_axis_distance(rect: PxRect, focused_rect: PxRect, direction: FocusDirection) -> i64 {
    let distance = match direction {
        FocusDirection::Left => focused_rect.x.0 - focused_rect_right(rect).0,
        FocusDirection::Right => rect.x.0 - focused_rect_right(focused_rect).0,
        FocusDirection::Up => focused_rect.y.0 - focused_rect_bottom(rect).0,
        FocusDirection::Down => rect.y.0 - focused_rect_bottom(focused_rect).0,
        _ => 0,
    };
    i64::from(distance.max(0))
}

fn major_axis_distance_to_far_edge(rect: PxRect, source: PxRect, direction: FocusDirection) -> i64 {
    let distance = match direction {
        FocusDirection::Left => source.x.0 - rect.x.0,
        FocusDirection::Right => focused_rect_right(rect).0 - focused_rect_right(source).0,
        FocusDirection::Up => source.y.0 - rect.y.0,
        FocusDirection::Down => focused_rect_bottom(rect).0 - focused_rect_bottom(source).0,
        _ => 1,
    };
    i64::from(distance.max(1))
}

fn minor_axis_distance(rect: PxRect, focused_rect: PxRect, direction: FocusDirection) -> i64 {
    let focused_center = match direction {
        FocusDirection::Left | FocusDirection::Right => {
            focused_rect.y.0 + focused_rect.height.0 / 2
        }
        FocusDirection::Up | FocusDirection::Down => focused_rect.x.0 + focused_rect.width.0 / 2,
        _ => 0,
    };
    let candidate_center = match direction {
        FocusDirection::Left | FocusDirection::Right => rect.y.0 + rect.height.0 / 2,
        FocusDirection::Up | FocusDirection::Down => rect.x.0 + rect.width.0 / 2,
        _ => 0,
    };
    i64::from(focused_center - candidate_center)
}

fn focused_rect_right(rect: PxRect) -> crate::Px {
    rect.x + rect.width
}

fn focused_rect_bottom(rect: PxRect) -> crate::Px {
    rect.y + rect.height
}

pub(crate) fn flush_pending_focus_callbacks() {
    let callbacks = TesseraRuntime::with_mut(|runtime| {
        runtime
            .component_tree
            .take_pending_focus_callback_invocations()
    });
    for callback in callbacks {
        callback.invoke();
    }
}