//! Focus and tab navigation management.

//!

//! Manages keyboard focus, tab navigation, and programmatic focus changes

//! with a recursive event system for focus/blur callbacks (max depth: 5).

use alloc::collections::BTreeMap;

use azul_core::{

    callbacks::{FocusTarget, FocusTargetPath},

    dom::{DomId, DomNodeId, NodeId},

    style::matches_html_element,

    styled_dom::NodeHierarchyItemId,

    window::UpdateFocusWarning,

};

use crate::window::DomLayoutResult;

/// Information about a pending contenteditable focus that needs cursor initialization

/// after layout is complete (W3C "flag and defer" pattern).

///

/// This is set during focus event handling and consumed after layout pass.

#[derive(Copy, Debug, Clone, PartialEq, Eq)]

pub struct PendingContentEditableFocus {

    /// The DOM where the contenteditable element is

    pub dom_id: DomId,

    /// The contenteditable container node that received focus

    pub container_node_id: NodeId,

    /// The text node where the cursor should be placed (often a child of the container)

    pub text_node_id: NodeId,

}

/// Manager for keyboard focus and tab navigation

///

/// Note: Text cursor management is now handled by the separate `CursorManager`.

///

/// The `FocusManager` only tracks which node has focus, while `CursorManager`

/// tracks the cursor position within that node (if it's contenteditable).

///

/// ## W3C Focus/Selection Model

///

/// The W3C model maintains a strict separation between **keyboard focus** and **selection**:

///

/// 1. **Focus** lands on the contenteditable container (`document.activeElement`)

/// 2. **Selection/Cursor** is placed in a descendant text node (`Selection.focusNode`)

///

/// This separation requires a "flag and defer" pattern:

/// - During focus event: Set `cursor_needs_initialization = true`

/// - After layout pass: Call `finalize_pending_focus_changes()` to actually initialize the cursor

///

/// This is necessary because cursor positioning requires text layout information,

/// which isn't available during the focus event handling phase.

#[derive(Debug, Clone, PartialEq, Eq)]

pub struct FocusManager {

    /// Currently focused node (if any)

    pub focused_node: Option<DomNodeId>,

    /// Pending focus request from callback

    pub pending_focus_request: Option<FocusTarget>,

    // --- W3C "flag and defer" pattern fields ---

    /// Flag indicating that cursor initialization is pending (set during focus, consumed after layout)

    pub cursor_needs_initialization: bool,

    /// Information about the pending contenteditable focus

    pub pending_contenteditable_focus: Option<PendingContentEditableFocus>,

    // --- focus-before-first-layout retry queue ---

    /// A [`FocusTarget`] that could not be resolved because no layout existed

    /// yet, kept so it can be re-resolved as soon as one does.

    ///

    /// `resolve_focus_target` answers `Ok(None)` with empty `layout_results`,

    /// and every caller reads `Ok(None)` as "clear focus" — so a programmatic

    /// `set_focus` issued from a `create` callback (which runs BEFORE the first

    /// layout) vanished without a trace, and apps papered over it with a

    /// short timer. Drained by

    /// `LayoutWindow::finalize_pending_focus_changes`, which runs after the

    /// layout pass.

    pub deferred_focus_target: Option<FocusTarget>,

    /// How many times the pending contenteditable focus has been re-armed for

    /// want of a text layout. Bounded so a node that will never have an inline

    /// layout cannot re-arm forever.

    pub pending_focus_retries: u8,

}

/// How many times [`FocusManager::pending_contenteditable_focus`] may be put

/// back because the text layout was not available yet.

pub const MAX_PENDING_FOCUS_RETRIES: u8 = 2;

/// Outcome of resolving a [`FocusTarget`] through

/// [`resolve_focus_target_or_defer`].

#[derive(Debug, Clone, Copy, PartialEq, Eq)]

pub enum FocusResolution {

    /// The target resolved. `None` means "clear focus" (`FocusTarget::NoFocus`,

    /// or a selector that matched nothing focusable) and MUST be applied.

    Resolved(Option<DomNodeId>),

    /// No layout existed yet, so the target was retained on the

    /// [`FocusManager`] and will be re-resolved after the first layout pass.

    /// Callers must leave the current focus alone.

    Deferred,

}

impl Default for FocusManager {

}

impl FocusManager {

    /// Create a new focus manager

    /// Get the currently focused node

    /// Set the focused node directly (used by event system)

    ///

    /// Note: Cursor initialization/clearing is now handled by `CursorManager`.

    /// The event system should check if the newly focused node is contenteditable

    /// and call `CursorManager::initialize_cursor_at_end()` if needed.

    /// Request a focus change (to be processed by event system)

    /// Take the pending focus request (one-shot)

    /// Clear focus

    /// Check if a specific node has focus

    // --- W3C "flag and defer" pattern methods ---

    /// Mark that cursor initialization is needed for a contenteditable element.

    ///

    /// This is called during focus event handling. The actual cursor initialization

    /// happens later in `finalize_pending_focus_changes()` after layout is complete.

    ///

    /// # W3C Conformance

    ///

    /// In the W3C model, when focus lands on a contenteditable element:

    /// 1. The focus event fires on the container element

    /// 2. The browser's editing engine modifies the Selection to place a caret

    /// 3. The Selection's anchorNode/focusNode point to the child text node

    ///

    /// Since we need layout information to position the cursor, we defer step 2+3.

    /// Put a just-taken pending contenteditable focus BACK because the text

    /// layout it needs did not exist yet. Returns `false` once

    /// [`MAX_PENDING_FOCUS_RETRIES`] is exhausted, in which case the caller

    /// must seed the cursor with whatever it has.

    /// Clear the pending contenteditable focus (when focus moves away or is cleared).

    /// Take the pending contenteditable focus (consumes the flag).

    ///

    /// Returns `Some(info)` if cursor initialization is pending, `None` otherwise.

    /// After calling this, `cursor_needs_initialization` is set to `false`.

        } else {

        }

    /// Check if cursor initialization is pending.

    // --- focus-before-first-layout retry queue ---

    /// Retain a focus target that had no layout to resolve against.

    ///

    /// A later request replaces an earlier one: only the most recent

    /// programmatic focus can win once layout arrives, exactly as it would if

    /// both had been resolvable immediately.

    /// Whether a focus target is waiting for the first layout.

    /// Take the deferred focus target (one-shot).

}

impl crate::managers::NodeIdRemap for FocusManager {

    /// Remap the focused node AND the pending contenteditable focus.

    ///

    /// Focus on an unmounted node is CLEARED (not kept — the index now denotes a

    /// different element).

        // 1. currently focused node

                {

                }

        // 2. pending contenteditable focus (set during focus handling, consumed

        //    after layout — a DOM rebuild can land in between).

}

/// MWA-C-focus_cursor: W3C sequential focus order over all DOMs.

///

/// Ordering: nodes with a positive `tabindex` (`TabIndex::OverrideInParent(n)`,

/// n >= 1) come first, ascending by n (stable sort, so document order breaks

/// ties); then all remaining keyboard-focusable nodes (`Auto`,

/// `OverrideInParent(0)`, implicit focusables) in document order.

/// `TabIndex::NoKeyboardFocus` (tabindex=-1) nodes stay focusable by click /

/// API but are NEVER part of the Tab order. The previous linear `NodeId` walk

/// both ignored positive-tabindex ordering and tabbed onto tabindex=-1 nodes.

    use azul_core::dom::TabIndex;

            };

            }

        }

    }

/// Pure merge of the two tab-order sections (split out for unit testing).

/// Document-order key for a node (DOM index, then arena index) — used to

/// re-enter the tab order from a node that is not itself tab-focusable.

    (

    )

/// Pick the next / previous entry in `order` relative to `current`.

///

/// If `current` is a tab stop, steps with wrap-around. If it is not (no focus

/// yet, or focus sits on a tabindex=-1 / removed node), forward picks the

/// first tab stop after it in document order (wrapping to the first entry),

/// backward symmetrically.

        } else {

        };

    };

        } else {

        };

    } else {

    };

        } else {

        }

/// Context for focus-target resolution (`Path` / `Id` lookups).

///

/// MWA-C-focus_cursor: the old linear-walk machinery (`SearchDirection`,

/// `search_focusable_node`, `get_*_start`) was replaced by the W3C tab order

/// built in `collect_tab_order`; only the layout lookup helpers remain.

struct FocusSearchContext<'a> {

    /// Reference to all DOM layouts in the window

    layout_results: &'a BTreeMap<DomId, DomLayoutResult>,

}

impl<'a> FocusSearchContext<'a> {

    /// Create a new search context from layout results.

    /// Get the layout for a DOM ID, or return an error if invalid.

    #[allow(clippy::trivially_copy_pass_by_ref)] // <=8B Copy param kept by-ref intentionally (hot pixel/coord path or to avoid churning call sites for a perf-neutral change)

    /// Construct a `DomNodeId` from DOM and node IDs.

}

/// Find the first focusable node matching a CSS path selector.

///

/// Iterates through all nodes in the DOM in document order (index 0..n),

/// and returns the first node that:

///

/// 1. Matches the CSS path selector

/// 2. Is focusable (has `tabindex` or is naturally focusable)

///

/// # Returns

///

/// * `Ok(Some(node))` - Found a matching focusable node

/// * `Ok(None)` - No matching focusable node exists

/// * `Err(_)` - CSS path could not be matched (malformed selector)

#[allow(clippy::trivially_copy_pass_by_ref)] // <=8B Copy param kept by-ref intentionally (hot pixel/coord path or to avoid churning call sites for a perf-neutral change)

    // Iterate through all nodes in document order

            // Check if node matches the CSS path (no pseudo-selector requirement)

            )

            // Among matching nodes, find first that is focusable

/// Resolve a `FocusTarget`, or QUEUE it when there is no layout to resolve

/// against yet.

///

/// This is the entry point every focus-changing caller should use.

/// [`resolve_focus_target`] cannot tell "nothing matched" from "nothing exists

/// yet": both are `Ok(None)`, and callers apply that as "clear focus". A

/// `set_focus` issued from a `create` callback — which runs before the first

/// layout — was therefore dropped on the floor.

///

/// # Errors

///

/// Returns an `UpdateFocusWarning` if the focus target cannot be resolved.

    // `NoFocus` means the app WANTS focus cleared; that is answerable without

    // any layout and must not be queued (it would then fire later, clearing a

    // focus the app had meanwhile set).

/// Resolve a `FocusTarget` to an actual `DomNodeId`

///

/// Prefer [`resolve_focus_target_or_defer`]: with empty `layout_results` this

/// answers `Ok(None)`, which is indistinguishable from "clear focus".

///

/// # Errors

///

/// Returns an `UpdateFocusWarning` if the focus target cannot be resolved.

    use azul_core::callbacks::FocusTarget::{Path, Id, Previous, Next, First, Last, NoFocus};

        }

            } else {

            }

        }

        // MWA-C-focus_cursor: sequential navigation goes through the W3C tab

        // order (positive tabindex ascending, then document order; -1

        // excluded) instead of the old raw-NodeId walk.

    }

// Trait Implementations for Event Filtering

impl azul_core::events::FocusManagerQuery for FocusManager {

}

#[cfg(test)]

mod tab_order_tests {

    use super::*;

    #[test]

        // Document order: n3 (tabindex=2), n5 (auto), n7 (tabindex=1), n9 (auto)

        );

    #[test]

    #[test]

    #[test]

    #[test]

        // Focus sits on a tabindex=-1 node (0,5): Tab goes to the next tab

        // stop in document order (0,6); Shift+Tab to the previous one (0,4).

        // Past the last stop: wraps to first / last respectively.

    #[test]

}

#[cfg(test)]

mod autotest_generated {

    use std::collections::HashMap;

    use azul_core::{

        dom::{Dom, NodeType, TabIndex},

        geom::LogicalRect,

        styled_dom::StyledDom,

    };

    use azul_css::css::{CssPath, CssPathSelector};

    use super::*;

    use crate::{

        managers::{NodeIdMap, NodeIdRemap},

        solver3::{display_list::DisplayList, layout_tree::LayoutTree},

    };

    // ------------------------------------------------------------------

    // Fixtures

    // ------------------------------------------------------------------

    fn dom(inner: usize) -> DomId {

        DomId { inner }

    }

    fn nid(dom_idx: usize, node: usize) -> DomNodeId {

        FocusSearchContext::make_dom_node_id(dom(dom_idx), NodeId::new(node))

    }

    /// A `DomNodeId` whose node slot is the "no node" sentinel (`inner == 0`).

    fn null_nid(dom_idx: usize) -> DomNodeId {

        DomNodeId {

            dom: dom(dom_idx),

            node: NodeHierarchyItemId::from_crate_internal(None),

        }

    }

    /// `DomLayoutResult` with an empty layout tree — every function under test

    /// here reads only `styled_dom`, so no real layout (and no font) is needed.

    fn layout_result(styled_dom: StyledDom) -> DomLayoutResult {

        DomLayoutResult {

            styled_dom,

            layout_tree: LayoutTree {

                nodes: Vec::new(),

                warm: Vec::new(),

                cold: Vec::new(),

                root: 0,

                dom_to_layout: BTreeMap::new(),

                children_arena: Vec::new(),

                children_offsets: Vec::new(),

                subtree_needs_intrinsic: Vec::new(),

            },

            calculated_positions: Vec::new(),

            viewport: LogicalRect::zero(),

            display_list: std::sync::Arc::new(DisplayList::default()),

            scroll_ids: HashMap::new(),

            scroll_id_to_node_id: HashMap::new(),

        }

    }

    fn window(entries: Vec<(DomId, StyledDom)>) -> BTreeMap<DomId, DomLayoutResult> {

        entries

            .into_iter()

            .map(|(id, sd)| (id, layout_result(sd)))

            .collect()

    }

    /// Flat (pre-order) indices of [`tab_fixture`]:

    ///

    /// | idx | node                    | focusable | tab bucket        |

    /// |-----|-------------------------|-----------|-------------------|

    /// | 0   | body                    | no        | —                 |

    /// | 1   | div (plain)             | no        | —                 |

    /// | 2   | button                  | yes       | auto              |

    /// | 3   | div `tabindex=2`        | yes       | positive (n=2)    |

    /// | 4   | div `tabindex=-1`       | yes       | EXCLUDED          |

    /// | 5   | div `tabindex=1`        | yes       | positive (n=1)    |

    /// | 6   | div `tabindex=0`        | yes       | auto              |

    /// | 7   | textarea                | yes       | auto              |

    ///

    /// => tab order `[5, 3, 2, 6, 7]`.

    fn tab_fixture() -> StyledDom {

        StyledDom::create_from_dom(

            Dom::create_body()

                .with_child(Dom::create_div())

                .with_child(Dom::create_node(NodeType::Button))

                .with_child(Dom::create_div().with_tab_index(TabIndex::OverrideInParent(2)))

                .with_child(Dom::create_div().with_tab_index(TabIndex::NoKeyboardFocus))

                .with_child(Dom::create_div().with_tab_index(TabIndex::OverrideInParent(1)))

                .with_child(Dom::create_div().with_tab_index(TabIndex::OverrideInParent(0)))

                .with_child(Dom::create_node(NodeType::TextArea)),

        )

    }

    fn tab_order_of(fixture: StyledDom) -> Vec<DomNodeId> {

        collect_tab_order(&window(vec![(dom(0), fixture)]))

    }

    fn class_path(class: &str) -> CssPath {

        CssPath {

            selectors: vec![CssPathSelector::Class(class.to_string().into())].into(),

        }

    }

    // ==================================================================

    // FocusManager — constructor / getters / predicates

    // ==================================================================

    #[test]

    fn focus_manager_new_matches_default_and_is_fully_empty() {

        let fm = FocusManager::new();

        assert_eq!(fm, FocusManager::default());

        assert_eq!(fm.get_focused_node(), None);

        assert!(!fm.needs_cursor_initialization());

        assert_eq!(fm.pending_focus_request, None);

        assert_eq!(fm.pending_contenteditable_focus, None);

        // A default instance must answer every query without panicking.

        assert!(!fm.has_focus(&nid(0, 0)));

        assert!(!fm.has_focus(&null_nid(0)));

    }

    #[test]

    fn focus_manager_set_get_clear_focus_roundtrip() {

        let mut fm = FocusManager::new();

        fm.set_focused_node(Some(nid(0, 3)));

        assert_eq!(fm.get_focused_node(), Some(&nid(0, 3)));

        assert!(fm.has_focus(&nid(0, 3)));

        // Explicitly setting `None` is equivalent to clearing.

        fm.set_focused_node(None);

        assert_eq!(fm.get_focused_node(), None);

        fm.set_focused_node(Some(nid(0, 3)));

        fm.clear_focus();

        assert_eq!(fm.get_focused_node(), None);

        assert!(!fm.has_focus(&nid(0, 3)));

        // Clearing twice is idempotent, not a panic.

        fm.clear_focus();

        assert_eq!(fm.get_focused_node(), None);

    }

    #[test]

    fn focus_manager_has_focus_discriminates_both_dom_and_node() {

        let mut fm = FocusManager::new();

        fm.set_focused_node(Some(nid(1, 4)));

        assert!(fm.has_focus(&nid(1, 4)));

        // Same node index, different DOM — must NOT be treated as focused.

        assert!(!fm.has_focus(&nid(0, 4)));

        assert!(!fm.has_focus(&nid(2, 4)));

        // Same DOM, different node index.

        assert!(!fm.has_focus(&nid(1, 3)));

        assert!(!fm.has_focus(&nid(1, 5)));

        // The "no node" sentinel must not alias node 0.

        assert!(!fm.has_focus(&null_nid(1)));

    }

    #[test]

    fn focus_manager_has_focus_on_null_node_sentinel_is_exact() {

        // Focusing the sentinel itself: it matches only the sentinel, and in

        // particular is NOT confused with real node index 0 (whose encoded

        // `NodeHierarchyItemId` is 1, not 0).

        let mut fm = FocusManager::new();

        fm.set_focused_node(Some(null_nid(0)));

        assert!(fm.has_focus(&null_nid(0)));

        assert!(!fm.has_focus(&nid(0, 0)));

        assert!(!fm.has_focus(&null_nid(1)));

    }

    #[test]

    fn focus_manager_focus_survives_extreme_node_index() {

        // `NodeHierarchyItemId` encodes `Some(n)` as `n + 1`, so `usize::MAX`

        // itself would overflow the encoding. `usize::MAX - 1` is the largest

        // representable node and must round-trip cleanly.

        let extreme = nid(usize::MAX, usize::MAX - 1);

        let mut fm = FocusManager::new();

        fm.set_focused_node(Some(extreme));

        assert!(fm.has_focus(&extreme));

        assert_eq!(

            fm.get_focused_node()

                .and_then(|n| n.node.into_crate_internal())

                .map(|n| n.index()),

            Some(usize::MAX - 1)

        );

    }

    // ==================================================================

    // FocusManager — pending focus request (one-shot)

    // ==================================================================

    #[test]

    fn focus_manager_take_focus_request_is_one_shot() {

        let mut fm = FocusManager::new();

        // Taking from a fresh manager yields None rather than panicking.

        assert_eq!(fm.take_focus_request(), None);

        fm.request_focus_change(FocusTarget::Next);

        assert_eq!(fm.take_focus_request(), Some(FocusTarget::Next));

        // Consumed — a second take must not replay the request.

        assert_eq!(fm.take_focus_request(), None);

        assert_eq!(fm.take_focus_request(), None);

    }

    #[test]

    fn focus_manager_request_focus_change_overwrites_pending_request() {

        // The field holds a single slot: a second request silently REPLACES the

        // first (requests are not queued). Pin that, so a change to queueing

        // semantics is a deliberate, visible break.

        let mut fm = FocusManager::new();

        fm.request_focus_change(FocusTarget::First);

        fm.request_focus_change(FocusTarget::Last);

        fm.request_focus_change(FocusTarget::NoFocus);

        assert_eq!(fm.take_focus_request(), Some(FocusTarget::NoFocus));

        assert_eq!(fm.take_focus_request(), None);

    }

    #[test]

    fn focus_manager_request_focus_change_accepts_every_variant() {

        let path = FocusTarget::Path(FocusTargetPath {

            dom: dom(usize::MAX),

            css_path: class_path("nonexistent"),

        });

        let targets = vec![

            FocusTarget::Id(nid(0, 0)),

            FocusTarget::Id(null_nid(usize::MAX)),

            path,

            FocusTarget::Previous,

            FocusTarget::Next,

            FocusTarget::First,

            FocusTarget::Last,

            FocusTarget::NoFocus,

        ];

        for t in targets {

            let mut fm = FocusManager::new();

            fm.request_focus_change(t.clone());

            assert_eq!(fm.take_focus_request(), Some(t));

        }

    }

    // ==================================================================

    // FocusManager — W3C "flag and defer" contenteditable state

    // ==================================================================

    #[test]

    fn focus_manager_pending_contenteditable_set_then_take_is_one_shot() {

        let mut fm = FocusManager::new();

        assert!(!fm.needs_cursor_initialization());

        assert_eq!(fm.take_pending_contenteditable_focus(), None);

        fm.set_pending_contenteditable_focus(dom(2), NodeId::new(7), NodeId::new(9));

        assert!(fm.needs_cursor_initialization());

        assert_eq!(

            fm.take_pending_contenteditable_focus(),

            Some(PendingContentEditableFocus {

                dom_id: dom(2),

                container_node_id: NodeId::new(7),

                text_node_id: NodeId::new(9),

            })

        );

        // Flag consumed; a second take must not replay the pending focus.

        assert!(!fm.needs_cursor_initialization());

        assert_eq!(fm.take_pending_contenteditable_focus(), None);

    }

    #[test]

    fn focus_manager_set_pending_contenteditable_overwrites_and_accepts_extremes() {

        let mut fm = FocusManager::new();

        fm.set_pending_contenteditable_focus(dom(0), NodeId::new(1), NodeId::new(2));

        // Extreme ids (and container == text, i.e. a degenerate self-reference)

        // must be stored verbatim without panicking.

        fm.set_pending_contenteditable_focus(

            dom(usize::MAX),

            NodeId::new(usize::MAX),

            NodeId::new(usize::MAX),

        );

        assert_eq!(

            fm.take_pending_contenteditable_focus(),

            Some(PendingContentEditableFocus {

                dom_id: dom(usize::MAX),

                container_node_id: NodeId::new(usize::MAX),

                text_node_id: NodeId::new(usize::MAX),

            })

        );

    }

    #[test]

    fn focus_manager_clear_pending_contenteditable_clears_flag_and_value() {

        let mut fm = FocusManager::new();

        fm.set_pending_contenteditable_focus(dom(0), NodeId::new(1), NodeId::new(2));

        fm.clear_pending_contenteditable_focus();

        assert!(!fm.needs_cursor_initialization());

        assert_eq!(fm.pending_contenteditable_focus, None);

        assert_eq!(fm.take_pending_contenteditable_focus(), None);

        // Clearing an already-clear manager is idempotent.

        fm.clear_pending_contenteditable_focus();

        assert!(!fm.needs_cursor_initialization());

    }

    #[test]

    fn focus_manager_take_pending_without_flag_strands_the_value() {

        // Both fields are `pub`, so the flag and the value can be desynced by a

        // direct field write. `take_pending_contenteditable_focus` gates purely

        // on the FLAG, so a value written without the flag is never handed out

        // and is left stranded in the manager. Pin the (safe, non-panicking)

        // behaviour: no cursor is initialised, and the stale value survives.

        let mut fm = FocusManager::new();

        fm.pending_contenteditable_focus = Some(PendingContentEditableFocus {

            dom_id: dom(0),

            container_node_id: NodeId::new(1),

            text_node_id: NodeId::new(2),

        });

        assert!(!fm.needs_cursor_initialization());

        assert_eq!(fm.take_pending_contenteditable_focus(), None);

        assert!(fm.pending_contenteditable_focus.is_some());

    }

    #[test]

    fn focus_manager_flag_without_value_take_returns_none_and_clears_flag() {

        // The mirror-image desync: flag set, value absent. `take` must report

        // "nothing to do" AND drop the flag, so the caller cannot spin on a

        // permanently-pending initialisation.

        let mut fm = FocusManager::new();

        fm.cursor_needs_initialization = true;

        assert!(fm.needs_cursor_initialization());

        assert_eq!(fm.take_pending_contenteditable_focus(), None);

        assert!(!fm.needs_cursor_initialization());

    }

    #[test]

    fn focus_manager_clear_focus_does_not_clear_pending_cursor_state() {

        // `clear_focus` touches ONLY `focused_node`: the deferred contenteditable

        // cursor request deliberately survives it (callers must call

        // `clear_pending_contenteditable_focus` themselves). Pin this, since a

        // silent change would either leak a cursor into an unfocused node or

        // drop a legitimate deferred cursor.

        let mut fm = FocusManager::new();

        fm.set_focused_node(Some(nid(0, 4)));

        fm.set_pending_contenteditable_focus(dom(0), NodeId::new(4), NodeId::new(5));

        fm.clear_focus();

        assert_eq!(fm.get_focused_node(), None);

        assert!(fm.needs_cursor_initialization());

        assert!(fm.pending_contenteditable_focus.is_some());

    }

    // ==================================================================

    // order_tab_entries / doc_order_key

    // ==================================================================

    #[test]

    fn order_tab_entries_empty_inputs_yield_empty() {

        assert_eq!(order_tab_entries(Vec::new(), Vec::new()), Vec::new());

    }

    #[test]

    fn order_tab_entries_u32_max_sorts_after_smaller_positives() {

        // No overflow / wrap: u32::MAX is just a very large key and must land

        // last among the positives, never first.

        let order = order_tab_entries(

            vec![

                (u32::MAX, nid(0, 1)),

                (1, nid(0, 2)),

                (u32::MAX - 1, nid(0, 3)),

            ],

            vec![nid(0, 4)],

        );

        assert_eq!(

            order,

            vec![nid(0, 2), nid(0, 3), nid(0, 1), nid(0, 4)],

            "u32::MAX must sort last among positives, and all positives before auto"

        );

    }

    #[test]

    fn order_tab_entries_positive_always_precedes_auto() {

        // Even the largest possible positive tabindex outranks every auto entry.

        let order = order_tab_entries(vec![(u32::MAX, nid(9, 99))], vec![nid(0, 0), nid(0, 1)]);

        assert_eq!(order[0], nid(9, 99));

        assert_eq!(order.len(), 3);

    }

    #[test]

    fn order_tab_entries_does_not_deduplicate() {

        // Duplicates are preserved verbatim (the function is a pure merge, not a

        // set builder) — a duplicated entry must not silently vanish.

        let order = order_tab_entries(

            vec![(1, nid(0, 1)), (1, nid(0, 1))],

            vec![nid(0, 2), nid(0, 2)],

        );

        assert_eq!(order, vec![nid(0, 1), nid(0, 1), nid(0, 2), nid(0, 2)]);

    }

    #[test]

    fn doc_order_key_null_node_collides_with_node_index_zero() {

        // `doc_order_key` maps the "no node" sentinel to arena index 0, so it is

        // indistinguishable from real node 0 within the same DOM. Pin the

        // collision: `next_in_tab_order`'s re-entry search relies on this key,

        // and a focus sitting on the sentinel therefore re-enters as if it sat

        // on node 0.

        assert_eq!(doc_order_key(&null_nid(0)), (0, 0));

        assert_eq!(doc_order_key(&nid(0, 0)), (0, 0));

        assert_eq!(doc_order_key(&null_nid(0)), doc_order_key(&nid(0, 0)));

    }

    #[test]

    fn doc_order_key_is_dom_major_then_arena_index() {

        assert_eq!(doc_order_key(&nid(3, 7)), (3, 7));

        // DOM index dominates: a huge node index in DOM 0 still precedes node 0

        // of DOM 1.

        assert!(doc_order_key(&nid(0, usize::MAX - 1)) < doc_order_key(&nid(1, 0)));

        assert_eq!(doc_order_key(&nid(usize::MAX, usize::MAX - 1)), (usize::MAX, usize::MAX - 1));

    }

    // ==================================================================

    // next_in_tab_order

    // ==================================================================

    #[test]

    fn next_in_tab_order_single_entry_wraps_onto_itself() {

        // `(0 + 1) % 1 == 0` — must terminate on itself, not loop or panic.

        let order = vec![nid(0, 1)];

        assert_eq!(next_in_tab_order(&order, Some(nid(0, 1)), true), Some(nid(0, 1)));

        assert_eq!(next_in_tab_order(&order, Some(nid(0, 1)), false), Some(nid(0, 1)));

    }

    #[test]

    fn next_in_tab_order_duplicate_entries_resolve_to_first_position() {

        // `position()` finds the FIRST occurrence, so a duplicated tab stop makes

        // the trailing copy unreachable by stepping. Pin it (a dedup in

        // `collect_tab_order` would change this).

        let order = vec![nid(0, 1), nid(0, 2), nid(0, 1)];

        assert_eq!(next_in_tab_order(&order, Some(nid(0, 1)), true), Some(nid(0, 2)));

        // Backward from index 0 wraps to the last element.

        assert_eq!(next_in_tab_order(&order, Some(nid(0, 1)), false), Some(nid(0, 1)));

    }

    #[test]

    fn next_in_tab_order_unknown_current_uses_cross_dom_document_order() {

        // Current node lives in DOM 1; the tab order is split across DOM 0 and 2.

        let order = vec![nid(0, 5), nid(2, 1)];

        assert_eq!(next_in_tab_order(&order, Some(nid(1, 0)), true), Some(nid(2, 1)));

        assert_eq!(next_in_tab_order(&order, Some(nid(1, 9)), false), Some(nid(0, 5)));

    }

    #[test]

    fn next_in_tab_order_unknown_current_past_both_ends_wraps() {

        let order = vec![nid(1, 2), nid(1, 4)];

        // Nothing greater -> wrap to first.

        assert_eq!(next_in_tab_order(&order, Some(nid(9, 9)), true), Some(nid(1, 2)));

        // Nothing smaller -> wrap to last.

        assert_eq!(next_in_tab_order(&order, Some(nid(0, 0)), false), Some(nid(1, 4)));

    }

    #[test]

    fn next_in_tab_order_null_current_node_is_deterministic() {

        // The sentinel keys as (dom, 0); it is not in the order, so the re-entry

        // path runs. It must produce a stable answer, not panic.

        let order = vec![nid(0, 1), nid(0, 3)];

        assert_eq!(next_in_tab_order(&order, Some(null_nid(0)), true), Some(nid(0, 1)));

        assert_eq!(next_in_tab_order(&order, Some(null_nid(0)), false), Some(nid(0, 3)));

    }

    #[test]

    fn next_in_tab_order_empty_order_is_none_for_every_input() {

        assert_eq!(next_in_tab_order(&[], None, true), None);

        assert_eq!(next_in_tab_order(&[], None, false), None);

        assert_eq!(next_in_tab_order(&[], Some(null_nid(0)), true), None);

        assert_eq!(

            next_in_tab_order(&[], Some(nid(usize::MAX, usize::MAX - 1)), false),

            None

        );

    }

    // ==================================================================

    // collect_tab_order

    // ==================================================================

    #[test]

    fn collect_tab_order_empty_window_is_empty() {

        assert_eq!(collect_tab_order(&BTreeMap::new()), Vec::new());

    }

    #[test]

    fn collect_tab_order_dom_without_focusables_is_empty() {

        let sd = StyledDom::create_from_dom(

            Dom::create_body()

                .with_child(Dom::create_div())

                .with_child(Dom::create_div()),

        );

        assert_eq!(tab_order_of(sd), Vec::new());

    }

    #[test]

    fn collect_tab_order_positives_first_then_document_order_minus_one_excluded() {

        // See `tab_fixture` doc comment for the expected layout.

        assert_eq!(

            tab_order_of(tab_fixture()),

            vec![nid(0, 5), nid(0, 3), nid(0, 2), nid(0, 6), nid(0, 7)],

            "tabindex=1 then tabindex=2, then auto nodes in document order"

        );

    }

    #[test]

    fn collect_tab_order_excludes_tabindex_minus_one_though_it_is_focusable() {

        // The tabindex=-1 node (index 4) is click/API focusable but must NEVER be

        // a tab stop.

        let order = tab_order_of(tab_fixture());

        assert!(!order.contains(&nid(0, 4)), "tabindex=-1 must not be a tab stop");

        // ...and the plain, non-focusable div is absent too.

        assert!(!order.contains(&nid(0, 1)));

        // ...while the body itself is never a tab stop.

        assert!(!order.contains(&nid(0, 0)));

    }

    #[test]

    fn collect_tab_order_huge_tabindex_truncates_at_28_bits() {

        // `NodeFlags` packs the tabindex into 28 bits, so:

        //   * tabindex = u32::MAX  -> stored as 2^28-1  -> still POSITIVE

        //   * tabindex = 1 << 28   -> stored as 0       -> demoted to the AUTO

        //                                                  bucket (0 is not > 0)

        // The truncation is silent, so pin the observable ordering consequence.

        //

        // Document order: 1 = u32::MAX, 2 = 1<<28, 3 = tabindex 1, 4 = button.

        let sd = StyledDom::create_from_dom(

            Dom::create_body()

                .with_child(Dom::create_div().with_tab_index(TabIndex::OverrideInParent(u32::MAX)))

                .with_child(Dom::create_div().with_tab_index(TabIndex::OverrideInParent(1 << 28)))

                .with_child(Dom::create_div().with_tab_index(TabIndex::OverrideInParent(1)))

                .with_child(Dom::create_node(NodeType::Button)),

        );

        assert_eq!(

            tab_order_of(sd),

            vec![nid(0, 3), nid(0, 1), nid(0, 2), nid(0, 4)],

            "u32::MAX stays positive (sorts after tabindex=1); 1<<28 truncates to 0 and \

             falls back into the auto bucket behind every positive"

        );

    }

    #[test]

    fn collect_tab_order_tab_order_is_global_across_doms() {

        // A positive-tabindex node in DOM 1 must outrank an auto node in DOM 0:

        // the tab order is a single sequence over all DOMs, not per-DOM chunks.

        let order = collect_tab_order(&window(vec![

            (dom(0), tab_fixture()),

            (dom(1), tab_fixture()),

        ]));

        assert_eq!(

            order,

            vec![

                // positives, ascending; ties broken by DOM then document order

                nid(0, 5),

                nid(1, 5),

                nid(0, 3),

                nid(1, 3),

                // autos, in DOM order then document order

                nid(0, 2),

                nid(0, 6),

                nid(0, 7),

                nid(1, 2),

                nid(1, 6),

                nid(1, 7),

            ]

        );

    }

    // ==================================================================

    // FocusSearchContext

    // ==================================================================

    #[test]

    fn focus_search_context_get_layout_hit_and_miss() {

        let results = window(vec![(dom(0), tab_fixture())]);

        let ctx = FocusSearchContext::new(&results);

        // `DomLayoutResult` is not `PartialEq`, so compare on the error side only.

        assert!(ctx.get_layout(&dom(0)).is_ok());

        assert_eq!(

            ctx.get_layout(&dom(1)).err(),

            Some(UpdateFocusWarning::FocusInvalidDomId(dom(1)))

        );

        assert_eq!(

            ctx.get_layout(&dom(usize::MAX)).err(),

            Some(UpdateFocusWarning::FocusInvalidDomId(dom(usize::MAX)))

        );

    }

    #[test]

    fn focus_search_context_new_on_empty_map_never_resolves() {

        let empty = BTreeMap::new();

        let ctx = FocusSearchContext::new(&empty);

        assert_eq!(

            ctx.get_layout(&dom(0)).err(),

            Some(UpdateFocusWarning::FocusInvalidDomId(dom(0)))

        );

    }

    #[test]

    fn make_dom_node_id_round_trips_including_boundary_index() {

        // encode == decode for 0, a mid value, and the largest encodable index

        // (`usize::MAX` itself would overflow `NodeHierarchyItemId`'s n+1 encoding).

        for idx in [0usize, 1, 42, usize::MAX - 1] {

            let d = FocusSearchContext::make_dom_node_id(dom(7), NodeId::new(idx));

            assert_eq!(d.dom, dom(7));

            assert_eq!(d.node.into_crate_internal(), Some(NodeId::new(idx)));

            assert_eq!(doc_order_key(&d), (7, idx));

        }

    }

    // ==================================================================

    // find_first_matching_focusable_node

    // ==================================================================

    #[test]

    fn find_first_matching_skips_matching_but_unfocusable_nodes() {

        // Node 1 matches `.target` but is NOT focusable; node 2 matches AND is

        // focusable. The first *focusable* match must win.

        let sd = StyledDom::create_from_dom(

            Dom::create_body()

                .with_child(Dom::create_div().with_class("target".to_string().into()))

                .with_child(

                    Dom::create_div()

                        .with_class("target".to_string().into())

                        .with_tab_index(TabIndex::Auto),

                ),

        );

        let results = window(vec![(dom(0), sd)]);

        let layout = results.get(&dom(0)).unwrap();

        assert_eq!(

            find_first_matching_focusable_node(layout, &dom(0), &class_path("target")),

            Some(nid(0, 2))

        );

    }

    #[test]

    fn find_first_matching_empty_css_path_matches_nothing() {

        // A `CssPath` with zero selectors must not vacuously match every node.

        let results = window(vec![(dom(0), tab_fixture())]);

        let layout = results.get(&dom(0)).unwrap();

        let empty = CssPath {

            selectors: Vec::<CssPathSelector>::new().into(),

        };

        assert_eq!(

            find_first_matching_focusable_node(layout, &dom(0), &empty),

            None

        );

    }

    #[test]

    fn find_first_matching_unicode_class_matches_and_misses_cleanly() {

        // Non-ASCII / astral-plane class names must compare by exact string, with

        // no panic and no byte-index slicing surprises.

        let class = "クラス-día-🎯";

        let sd = StyledDom::create_from_dom(

            Dom::create_body().with_child(

                Dom::create_div()

                    .with_class(class.to_string().into())

                    .with_tab_index(TabIndex::Auto),

            ),

        );

        let results = window(vec![(dom(0), sd)]);

        let layout = results.get(&dom(0)).unwrap();

        assert_eq!(

            find_first_matching_focusable_node(layout, &dom(0), &class_path(class)),

            Some(nid(0, 1))

        );

        // A near-miss (same prefix, different suffix) must NOT match.

        assert_eq!(

            find_first_matching_focusable_node(layout, &dom(0), &class_path("クラス-día-🎲")),

            None

        );

        // A huge class name that cannot exist in the DOM also just misses.

        let huge = "x".repeat(10_000);

        assert_eq!(

            find_first_matching_focusable_node(layout, &dom(0), &class_path(&huge)),

            None

        );

    }

    // ==================================================================

    // resolve_focus_target

    // ==================================================================

    #[test]