//! Text selection and cursor positioning for inline content.

//!

//! This module provides data structures for managing text cursors and selection ranges

//! in a bidirectional (Bidi) and line-breaking aware manner. It handles:

//!

//! - **Grapheme cluster identification**: Unicode-aware character boundaries

//! - **Bidi support**: Cursor movement in mixed LTR/RTL text

//! - **Stable positions**: Selection anchors survive layout changes

//! - **Affinity tracking**: Cursor position at leading/trailing edges

//! - **Multi-node selection**: Browser-style selection spanning multiple DOM nodes

//!

//! # Architecture

//!

//! Text positions are represented as:

//! - `ContentIndex`: Logical position in the original inline content array

//! - `GraphemeClusterId`: Stable identifier for a grapheme cluster (survives reordering)

//! - `TextCursor`: Precise cursor location with leading/trailing affinity

//! - `SelectionRange`: Start and end cursors defining a selection

//!

//! Multi-node selection uses an Anchor/Focus model (W3C Selection API):

//! - `SelectionAnchor`: Fixed point where user started selection (mousedown)

//! - `SelectionFocus`: Movable point where selection currently ends (drag position)

//! - `TextSelection`: Complete selection state spanning potentially multiple IFC roots

//!

//! # Use Cases

//!

//! - Text editing: Insert/delete at cursor position

//! - Selection rendering: Highlight selected text across multiple nodes

//! - Keyboard navigation: Move cursor by grapheme/word/line

//! - Mouse selection: Convert pixel coordinates to text positions

//! - Drag selection: Extend selection across multiple DOM nodes

//!

//! # Examples

//!

//! ```rust,no_run

//! use azul_core::selection::{CursorAffinity, GraphemeClusterId, TextCursor};

//!

//! let cursor = TextCursor {

//!     cluster_id: GraphemeClusterId {

//!         source_run: 0,

//!         start_byte_in_run: 0,

//!     },

//!     affinity: CursorAffinity::Leading,

//! };

//! ```

use alloc::collections::BTreeMap;

use alloc::vec::Vec;

use core::sync::atomic::{AtomicU64, Ordering};

use crate::dom::{DomId, DomNodeId, NodeId};

use crate::geom::{LogicalPosition, LogicalRect};

/// A stable, logical pointer to an item within the original `InlineContent` array.

///

/// This structure eliminates the need for string concatenation and byte-offset math

/// by tracking both the run index and the item index within that run.

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

pub struct ContentIndex {

    /// The index of the `InlineContent` run in the original input array.

    pub run_index: u32,

    /// The byte index of the character or item *within* that run's string.

    pub item_index: u32,

}

/// A stable, logical identifier for a grapheme cluster.

///

/// This survives Bidi reordering and line breaking, making it ideal for tracking

/// text positions for selection and cursor logic.

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

#[repr(C)]

pub struct GraphemeClusterId {

    /// The `run_index` from the source `ContentIndex`.

    pub source_run: u32,

    /// The byte index of the start of the cluster in its original `StyledRun`.

    pub start_byte_in_run: u32,

}

/// Represents the logical position of the cursor *between* two grapheme clusters

/// or at the start/end of the text.

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

#[repr(C)]

pub enum CursorAffinity {

    /// The cursor is at the leading edge of the character (left in LTR, right in RTL).

    Leading,

    /// The cursor is at the trailing edge of the character (right in LTR, left in RTL).

    Trailing,

}

/// Represents a precise cursor location in the logical text.

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

#[repr(C)]

pub struct TextCursor {

    /// The grapheme cluster the cursor is associated with.

    pub cluster_id: GraphemeClusterId,

    /// The edge of the cluster the cursor is on.

    pub affinity: CursorAffinity,

}

impl_option!(

    TextCursor,

    OptionTextCursor,

    [Debug, Clone, Copy, PartialEq, Eq, Hash, Ord, PartialOrd]

);

/// Represents a range of selected text. The direction is implicit (start can be

/// logically after end if selecting backwards).

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

#[repr(C)]

pub struct SelectionRange {

    pub start: TextCursor,

    pub end: TextCursor,

}

impl_option!(

    SelectionRange,

    OptionSelectionRange,

    [Debug, Clone, Copy, PartialEq, Eq, Hash, Ord, PartialOrd]

);

impl_vec!(SelectionRange, SelectionRangeVec, SelectionRangeVecDestructor, SelectionRangeVecDestructorType, SelectionRangeVecSlice, OptionSelectionRange);

impl_vec_debug!(SelectionRange, SelectionRangeVec);

impl_vec_clone!(

    SelectionRange,

    SelectionRangeVec,

    SelectionRangeVecDestructor

);

impl_vec_partialeq!(SelectionRange, SelectionRangeVec);

impl_vec_partialord!(SelectionRange, SelectionRangeVec);

/// A single selection, which can be either a blinking cursor or a highlighted range.

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

#[repr(C, u8)]

pub enum Selection {

    Cursor(TextCursor),

    Range(SelectionRange),

}

impl_option!(

    Selection,

    OptionSelection,

    [Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord]

);

impl_vec!(Selection, SelectionVec, SelectionVecDestructor, SelectionVecDestructorType, SelectionVecSlice, OptionSelection);

impl_vec_debug!(Selection, SelectionVec);

impl_vec_clone!(Selection, SelectionVec, SelectionVecDestructor);

impl_vec_partialeq!(Selection, SelectionVec);

impl_vec_partialord!(Selection, SelectionVec);

/// The complete selection state for a single text block, supporting multiple cursors/ranges.

#[derive(Debug, Clone, PartialEq)]

#[repr(C)]

pub struct SelectionState {

    /// A list of all active selections. This list is kept sorted and non-overlapping.

    pub selections: SelectionVec,

    /// The DOM node this selection state applies to.

    pub node_id: DomNodeId,

}

impl SelectionState {

    /// Adds a new selection, merging it with any existing selections it overlaps with.

        // A full implementation would handle merging overlapping ranges.

        // For now, we simply add and sort for simplicity.

}

impl_option!(

    SelectionState,

    OptionSelectionState,

    copy = false,

    clone = false,

    [Debug, Clone, PartialEq]

);

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

// MULTI-CURSOR SUPPORT (Sublime Text style)

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

/// Stable identifier for a cursor/selection within a `MultiCursorState`.

///

/// Uses a monotonic u64 counter (not UUID) so it is `Copy` and C-API friendly.

/// Each `SelectionId` is unique within the lifetime of the process.

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

#[repr(C)]

pub struct SelectionId {

    pub inner: u64,

}

impl SelectionId {

    /// Generate a new unique `SelectionId`.

        static COUNTER: AtomicU64 = AtomicU64::new(1);

}

/// Note: `Default` generates a new unique ID (increments global counter),

/// rather than returning a zero/sentinel value.

impl Default for SelectionId {

}

impl_option!(

    SelectionId,

    OptionSelectionId,

    [Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord]

);

impl_vec!(SelectionId, SelectionIdVec, SelectionIdVecDestructor, SelectionIdVecDestructorType, SelectionIdVecSlice, OptionSelectionId);

impl_vec_debug!(SelectionId, SelectionIdVec);

impl_vec_clone!(SelectionId, SelectionIdVec, SelectionIdVecDestructor);

impl_vec_partialeq!(SelectionId, SelectionIdVec);

impl_vec_partialord!(SelectionId, SelectionIdVec);

/// A selection (cursor or range) paired with a stable identity.

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

#[repr(C)]

pub struct IdentifiedSelection {

    pub id: SelectionId,

    pub selection: Selection,

}

impl_option!(

    IdentifiedSelection,

    OptionIdentifiedSelection,

    [Debug, Clone, Copy, PartialEq, Eq, Hash]

);

impl_vec!(IdentifiedSelection, IdentifiedSelectionVec, IdentifiedSelectionVecDestructor, IdentifiedSelectionVecDestructorType, IdentifiedSelectionVecSlice, OptionIdentifiedSelection);

impl_vec_debug!(IdentifiedSelection, IdentifiedSelectionVec);

impl_vec_clone!(IdentifiedSelection, IdentifiedSelectionVec, IdentifiedSelectionVecDestructor);

impl_vec_partialeq!(IdentifiedSelection, IdentifiedSelectionVec);

/// Multi-cursor state for a contenteditable element (Sublime Text style).

///

/// Replaces the split `CursorManager` + `SelectionManager` pattern for text editing.

/// Supports multiple simultaneous cursors/selections, each with a stable ID.

///

/// ## Invariants

///

/// - `selections` is sorted by position and non-overlapping.

/// - The **primary** selection is identified by the stable `primary_id`, NOT by

///   vector position: `merge_overlapping()` re-sorts `selections` by position,

///   so "last index" is not the most-recently-added cursor.

/// - After any mutation, `merge_overlapping()` is called to maintain invariants.

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

pub struct MultiCursorState {

    /// Sorted by position, non-overlapping. Primary is tracked via `primary_id`.

    pub selections: Vec<IdentifiedSelection>,

    /// Stable ID of the primary selection (most recently added/set). Survives the

    /// position sort in `merge_overlapping`, which would otherwise make the

    /// vector's last element (position-last) masquerade as the primary.

    pub primary_id: SelectionId,

    /// The DOM node this multi-cursor state applies to.

    pub node_id: DomNodeId,

    /// Stable key that survives DOM rebuilds (from `calculate_contenteditable_key`).

    pub contenteditable_key: u64,

}

impl MultiCursorState {

    /// Create a new `MultiCursorState` with a single cursor.

    /// Add a cursor, merging if it overlaps with existing selections.

    /// Returns the `SelectionId` of the new (or merged) cursor.

    #[must_use]

    /// Add a selection range, merging if it overlaps.

    /// Returns the `SelectionId` of the new (or merged) selection.

    #[must_use]

    /// Remove a selection by its stable ID. Returns true if found and removed.

    #[must_use]

    /// Get the primary selection (the most recently added/set, tracked by

    /// `primary_id` — NOT the vector's last element, which position-sorting

    /// reorders). Falls back to the last element if `primary_id` was somehow

    /// lost.

    /// Get a mutable reference to the primary selection (see `get_primary`).

    /// Ensure `primary_id` names a selection that still exists; if not, adopt the

    /// last selection's id (best effort) so `get_primary` stays meaningful.

    /// Get the primary cursor position (for scroll-into-view, IME, etc.)

    /// Convert to a Vec<Selection> for passing to `edit_text()`.

    /// Update selections from the result of `edit_text()`.

    ///

    /// Preserves existing IDs where possible (by index), assigns new IDs for extras.

        // IDs are reassigned by index; make sure primary_id still resolves.

        // Don't merge here — edit_text already returns correct positions

    /// Set all selections to a single cursor (e.g., on plain click without Ctrl).

    /// Set all selections to a single range.

    /// Number of active cursors/selections.

    /// Whether there are no selections (should not normally happen).

    /// Sort selections by position and merge any that overlap.

        // Capture the primary before sorting/merging reorders and rewrites IDs.

        // Sort by the start position of each selection

        // Merge overlapping: if selection[i+1] starts at or before selection[i] ends,

        // merge them into one range (keeping the later ID as it's more recent).

                    // Overlap — merge into one range covering both

                    // If either side of the merge — or the accumulator that has

                    // already absorbed the primary earlier in the chain — was the

                    // primary, the merged selection inherits primary status.

                    // `last.id == new_primary` carries the primary across a 3+-link

                    // chain: without it, `new_primary` would keep pointing at an

                    // intermediate id that the next merge overwrites, and

                    // `ensure_primary_valid` would then adopt an unrelated tail.

                    // Keep the newer ID (the one being merged in)

        }

        // Point primary at a surviving selection (fallback: last element).

    /// Move all cursors using a movement function. Merges collisions afterward.

    ///

    /// `move_fn` takes a `TextCursor` and returns the new `TextCursor` after movement.

    /// If `extend_selection` is true, the anchor stays and only the focus moves,

    /// creating or extending a range.

    ///

    /// A bare (non-extending) move over an active range COLLAPSES to the range

    /// boundary — the arrow-key rule. Use [`Self::move_all_cursors_with`] for

    /// steps where that is wrong (Home/End, document jumps).

    /// [`Self::move_all_cursors`], with control over what a bare move does to

    /// an active range.

    ///

    /// `collapse_range_to_boundary` is the arrow-key rule: Left/Right with a

    /// selection put the caret on the selection's edge and go no further.

    /// Every OTHER step — Home/End, Ctrl+Home/End, a visual line, a word — is a

    /// MOVEMENT and must be performed: collapsing them to the nearest edge is

    /// how pressing End with text selected used to leave the caret sitting at

    /// the end of the selection instead of the end of the line.

                }

                        // Bare arrow with an active selection collapses the caret

                        // to the selection boundary in the arrow's direction WITHOUT

                        // advancing a character (standard editor behavior). Running

                        // move_fn on the focus and using that as the caret would step

                        // one unit past the edge. We don't get the arrow direction

                        // here, so probe it: apply move_fn to the focus and compare —

                        // a forward move collapses to the max boundary, a backward

                        // move to the min boundary.

                        } else {

                        };

                }

            }

        }

    /// Remap the `NodeId` in `node_id` after DOM reconciliation.

    ///

    /// If the node was removed (not in the map), the multi-cursor state is cleared.

}

/// Helper: get the start position of a Selection for sorting.

        }

    }

/// Helper: get the end position of a Selection for merging.

        }

    }

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

// MULTI-NODE SELECTION (Browser-style Anchor/Focus model)

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

/// The anchor point of a text selection - where the user started selecting.

///

/// This is the fixed point during a drag operation. It records:

/// - The IFC root node (where the `UnifiedLayout` lives)

/// - The exact cursor position within that layout

/// - The visual bounds of the anchor character (for logical rectangle calculations)

///

/// The anchor remains constant during a drag; only the focus moves.

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

pub struct SelectionAnchor {

    /// The IFC root node ID where selection started.

    /// This is the node that has `inline_layout_result` (e.g., `<p>`, `<div>`).

    pub ifc_root_node_id: NodeId,

    /// The exact cursor position within the IFC's `UnifiedLayout`.

    pub cursor: TextCursor,

    /// Visual bounds of the anchor character in viewport coordinates.

    /// Used for computing the logical selection rectangle during multi-line/multi-node selection.

    pub char_bounds: LogicalRect,

    /// The mouse position when the selection started (viewport coordinates).

    pub mouse_position: LogicalPosition,

}

/// The focus point of a text selection - where the selection currently ends.

///

/// This is the movable point during a drag operation. It updates on every mouse move.

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

pub struct SelectionFocus {

    /// The IFC root node ID where selection currently ends.

    /// May differ from anchor's IFC root during cross-node selection.

    pub ifc_root_node_id: NodeId,

    /// The exact cursor position within the IFC's `UnifiedLayout`.

    pub cursor: TextCursor,

    /// Current mouse position in viewport coordinates.

    pub mouse_position: LogicalPosition,

}

/// Complete selection state spanning potentially multiple DOM nodes.

///

/// This implements the W3C Selection API model with anchor/focus endpoints.

/// The selection can span multiple IFC roots (e.g., multiple `<p>` elements).

///

/// ## Storage Model

///

/// Uses `BTreeMap<NodeId, Vec<SelectionRange>>` for O(log N) lookup during rendering.

/// The key is the **IFC root `NodeId`**, and the value is every `SelectionRange`

/// that IFC contributes.

///

/// ## Example

///

/// ```text

/// <p id="1">Hello [World</p>     <- Anchor in IFC 1, partial selection

/// <p id="2">Complete line</p>    <- InBetween, fully selected

/// <p id="3">Partial] end</p>     <- Focus in IFC 3, partial selection

/// ```

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

pub struct TextSelection {

    /// The DOM this selection belongs to.

    pub dom_id: DomId,

    /// The anchor point - where the selection started (fixed during drag).

    pub anchor: SelectionAnchor,

    /// The focus point - where the selection currently ends (moves during drag).

    pub focus: SelectionFocus,

    /// Map from IFC root `NodeId` to the `SelectionRange`s for that IFC.

    /// This allows O(log N) lookup during rendering.

    ///

    /// Each `SelectionRange` contains the actual `TextCursor` positions for that IFC,

    /// ready to be passed to `UnifiedLayout::get_selection_rects()`.

    ///

    /// A node carries SEVERAL ranges when a multi-cursor session selects several

    /// occurrences in it (Ctrl+D); the ranges are disjoint and in document order.

    pub affected_nodes: BTreeMap<NodeId, Vec<SelectionRange>>,

    /// Indicates whether anchor comes before focus in document order.

    /// True = forward selection (left-to-right), False = backward selection.

    pub is_forward: bool,

}

impl TextSelection {

    /// Create a new collapsed selection (cursor) at the given position.

        // For a collapsed selection, the anchor node has a zero-width range

    /// Check if this is a collapsed selection (cursor with no range).

    /// Get the FIRST selection range for a specific IFC root node.

    /// Returns `None` if this node is not part of the selection.

    ///

    /// A multi-range node has more; [`Self::ranges_for_node`] returns all of them.

    /// Every range this IFC root contributes (empty slice when unaffected).

}

impl_option!(

    TextSelection,

    OptionTextSelection,

    copy = false,

    clone = false,

    [Debug, Clone, PartialEq, Eq]

);

#[cfg(test)]

mod audit_tests {

    use super::*;

    #[test]

        // Add a cursor at an EARLIER position; after merge_overlapping's sort it

        // becomes the vector's FIRST element, but it is the primary (last added).

        // The primary must be the just-added cursor at byte 0, not the

        // position-last cursor at byte 100.

    #[test]

        // primary_id must resolve to the surviving selection.

    #[test]

        // primary must now be a still-existing selection, not a dangling id.

}

#[cfg(test)]

mod autotest_generated {

    use super::*;

    use crate::geom::LogicalSize;

    use crate::styled_dom::NodeHierarchyItemId;

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

    // Fixtures

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

    /// Cursor in run 0 at `byte`, Leading affinity.

    fn c(byte: u32) -> TextCursor {

        TextCursor {

            cluster_id: GraphemeClusterId {

                source_run: 0,

                start_byte_in_run: byte,

            },

            affinity: CursorAffinity::Leading,

        }

    }

    /// Cursor with explicit run + affinity (for ordering / boundary probes).

    fn c_full(run: u32, byte: u32, affinity: CursorAffinity) -> TextCursor {

        TextCursor {

            cluster_id: GraphemeClusterId {

                source_run: run,

                start_byte_in_run: byte,

            },

            affinity,

        }

    }

    fn rng(a: u32, b: u32) -> SelectionRange {

        SelectionRange {

            start: c(a),

            end: c(b),

        }

    }

    fn dom_node(index: usize) -> DomNodeId {

        DomNodeId {

            dom: DomId::ROOT_ID,

            node: NodeHierarchyItemId::from_crate_internal(Some(NodeId::new(index))),

        }

    }

    fn state(byte: u32) -> MultiCursorState {

        MultiCursorState::new_with_cursor(c(byte), DomNodeId::ROOT, 0)

    }

    /// A `MultiCursorState` with zero selections — "should not normally happen",

    /// so every getter must survive it.

    fn empty_state() -> MultiCursorState {

        MultiCursorState {

            selections: Vec::new(),

            primary_id: SelectionId::new(),

            node_id: DomNodeId::ROOT,

            contenteditable_key: 0,

        }

    }

    fn ident(id: SelectionId, sel: Selection) -> IdentifiedSelection {

        IdentifiedSelection { id, selection: sel }

    }

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

    // Invariant checkers (documented in `MultiCursorState`'s `## Invariants`)

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

    /// `selections` is sorted by position and non-overlapping.

    fn assert_sorted_nonoverlapping(mc: &MultiCursorState) {

        for w in mc.selections.windows(2) {

            let prev_end = selection_end_pos(&w[0].selection);

            let next_start = selection_start_pos(&w[1].selection);

            assert!(

                next_start > prev_end,

                "selections must be sorted and non-overlapping after merge: {:?} then {:?}",

                w[0],

                w[1]

            );

        }

    }

    /// `primary_id` must always name a selection that actually exists (or the

    /// state must be empty). A dangling `primary_id` makes `get_primary()` lie.

    fn assert_primary_resolves(mc: &MultiCursorState) {

        if mc.is_empty() {

            assert!(mc.get_primary().is_none());

            assert!(mc.get_primary_cursor().is_none());

        } else {

            let p = mc.get_primary().expect("non-empty state must have a primary");

            assert!(

                mc.selections.iter().any(|s| s.id == p.id),

                "get_primary() returned a selection not in the vec"

            );

            assert_eq!(

                mc.primary_id, p.id,

                "primary_id must name an existing selection (not fall back to last)"

            );

        }

    }

    /// All selection IDs must be distinct.

    fn assert_ids_unique(mc: &MultiCursorState) {

        for (i, a) in mc.selections.iter().enumerate() {

            for b in mc.selections.iter().skip(i + 1) {

                assert_ne!(a.id, b.id, "duplicate SelectionId in state");

            }

        }

    }

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

    // SelectionId::new  (constructor)

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

    #[test]

    fn selection_id_new_is_unique_and_strictly_increasing() {

        let mut prev = SelectionId::new();

        assert!(prev.inner > 0, "counter starts at 1, never the 0 sentinel");

        for _ in 0..1000 {

            let next = SelectionId::new();

            // Other tests share the global atomic, so ids may skip — but within

            // one thread they must be strictly increasing and never repeat.

            assert!(

                next.inner > prev.inner,

                "SelectionId counter must be strictly monotonic"

            );

            assert_ne!(next, prev);

            prev = next;

        }

    }

    #[test]

    fn selection_id_default_mints_a_fresh_id() {

        // Documented: Default does NOT return a zero/sentinel value.

        let a = SelectionId::default();

        let b = SelectionId::default();

        let d = SelectionId::new();

        assert_ne!(a, b);

        assert_ne!(b, d);

        assert!(a.inner > 0 && b.inner > 0);

    }

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

    // SelectionState::add

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

    #[test]

    fn selection_state_add_dedups_identical_cursors() {

        let mut st = SelectionState {

            selections: Vec::<Selection>::new().into(),

            node_id: DomNodeId::ROOT,

        };

        for _ in 0..100 {

            st.add(Selection::Cursor(c(42)));

        }

        assert_eq!(st.selections.as_ref().len(), 1);

        assert_eq!(st.selections.as_ref()[0], Selection::Cursor(c(42)));

    }

    #[test]

    fn selection_state_add_sorts_descending_input_ascending() {

        let mut st = SelectionState {

            selections: Vec::<Selection>::new().into(),

            node_id: DomNodeId::ROOT,

        };

        for byte in [90u32, 10, 50, 0, 70] {

            st.add(Selection::Cursor(c(byte)));

        }

        let got: Vec<Selection> = st.selections.as_ref().to_vec();

        assert_eq!(got.len(), 5);

        let want: Vec<Selection> = [0u32, 10, 50, 70, 90]

            .iter()

            .map(|b| Selection::Cursor(c(*b)))

            .collect();

        assert_eq!(got, want);

    }

    #[test]

    fn selection_state_add_boundary_and_reversed_ranges_do_not_panic() {

        let mut st = SelectionState {

            selections: Vec::<Selection>::new().into(),

            node_id: DomNodeId::ROOT,

        };

        // u32::MAX bytes, max run index, both affinities, and a *reversed* range

        // (start logically after end — explicitly allowed by SelectionRange docs).

        st.add(Selection::Cursor(c_full(

            u32::MAX,

            u32::MAX,

            CursorAffinity::Trailing,

        )));

        st.add(Selection::Cursor(c_full(0, 0, CursorAffinity::Leading)));

        st.add(Selection::Range(SelectionRange {

            start: c_full(u32::MAX, u32::MAX, CursorAffinity::Trailing),

            end: c_full(0, 0, CursorAffinity::Leading),

        }));

        st.add(Selection::Range(rng(0, u32::MAX)));

        // add() only sorts + dedups; it does not normalize or merge, so all 4 stay.

        assert_eq!(st.selections.as_ref().len(), 4);

        // ... and the result is sorted.

        let got: Vec<Selection> = st.selections.as_ref().to_vec();

        let mut sorted = got.clone();

        sorted.sort_unstable();

        assert_eq!(got, sorted);

    }

    #[test]

    fn selection_state_add_cursor_and_range_at_same_pos_are_distinct() {

        let mut st = SelectionState {

            selections: Vec::<Selection>::new().into(),

            node_id: DomNodeId::ROOT,

        };

        st.add(Selection::Range(rng(5, 5)));

        st.add(Selection::Cursor(c(5)));

        // A zero-width Range and a Cursor are different `Selection` variants,

        // so dedup() cannot collapse them.

        assert_eq!(st.selections.as_ref().len(), 2);

        // Cursor variant sorts before Range variant.

        assert_eq!(st.selections.as_ref()[0], Selection::Cursor(c(5)));

    }

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

    // MultiCursorState::new_with_cursor  (constructor)

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

    #[test]

    fn new_with_cursor_invariants_hold() {

        let node = dom_node(7);

        let mc = MultiCursorState::new_with_cursor(c(3), node, 0xDEAD_BEEF);

        assert_eq!(mc.len(), 1);

        assert!(!mc.is_empty());

        assert_eq!(mc.selections.len(), mc.len());

        assert_eq!(mc.primary_id, mc.selections[0].id);

        assert_eq!(mc.node_id, node);

        assert_eq!(mc.contenteditable_key, 0xDEAD_BEEF);

        assert_eq!(mc.get_primary_cursor(), Some(c(3)));

        assert_eq!(mc.to_selections(), vec![Selection::Cursor(c(3))]);

        assert_primary_resolves(&mc);

    }

    #[test]

    fn new_with_cursor_extreme_args_do_not_panic() {

        let mc = MultiCursorState::new_with_cursor(

            c_full(u32::MAX, u32::MAX, CursorAffinity::Trailing),

            dom_node(usize::MAX / 4),

            u64::MAX,

        );

        assert_eq!(mc.len(), 1);

        assert_eq!(mc.contenteditable_key, u64::MAX);

        assert_eq!(

            mc.get_primary_cursor(),

            Some(c_full(u32::MAX, u32::MAX, CursorAffinity::Trailing))

        );

        assert_primary_resolves(&mc);

    }

    #[test]

    fn two_states_get_distinct_ids() {

        let a = state(0);

        let b = state(0);

        assert_ne!(a.primary_id, b.primary_id);

    }

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

    // add_cursor / add_selection

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

    #[test]

    fn add_cursor_at_same_position_merges_to_one() {

        let mut mc = state(5);

        let b = mc.add_cursor(c(5));

        assert_eq!(mc.len(), 1);

        assert_eq!(mc.selections[0].selection, Selection::Cursor(c(5)));

        assert_eq!(mc.selections[0].id, b, "merge keeps the newer id");

        assert_primary_resolves(&mc);

        assert_ids_unique(&mc);

    }

    #[test]

    fn add_cursor_distinct_positions_stay_separate_and_sorted() {

        let mut mc = state(30);

        let _ = mc.add_cursor(c(10));

        let last = mc.add_cursor(c(20));

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

        // Sorted by position, NOT by insertion order.

        assert_eq!(mc.to_selections(), vec![

            Selection::Cursor(c(10)),

            Selection::Cursor(c(20)),

            Selection::Cursor(c(30)),

        ]);

        // Primary is the most recently added (byte 20), which is the *middle*

        // element — proving primary is tracked by id, not vec position.

        assert_eq!(mc.get_primary().unwrap().id, last);

        assert_eq!(mc.get_primary_cursor(), Some(c(20)));

        assert_sorted_nonoverlapping(&mc);

        assert_primary_resolves(&mc);

        assert_ids_unique(&mc);

    }

    #[test]

    fn add_cursor_same_byte_different_affinity_does_not_merge() {

        // Leading < Trailing, so cur_start(Trailing) > last_end(Leading) and the

        // merge condition (`cur_start <= last_end`) is false. Two carets survive

        // at the same byte offset.

        let mut mc = MultiCursorState::new_with_cursor(

            c_full(0, 4, CursorAffinity::Leading),

            DomNodeId::ROOT,

            0,

        );

        let _ = mc.add_cursor(c_full(0, 4, CursorAffinity::Trailing));

        assert_eq!(mc.len(), 2);

        assert_sorted_nonoverlapping(&mc);

        assert_primary_resolves(&mc);

    }

    #[test]

    fn add_selection_overlapping_ranges_merge_into_union() {

        let mut mc = empty_state();

        let _ = mc.add_selection(rng(0, 10));

        let _ = mc.add_selection(rng(5, 20));

        assert_eq!(mc.len(), 1);

        assert_eq!(mc.selections[0].selection, Selection::Range(rng(0, 20)));

        assert_primary_resolves(&mc);

    }

    #[test]

    fn add_selection_touching_ranges_merge() {

        // Adjacent (end == start) counts as overlapping: `cur_start <= last_end`.

        let mut mc = empty_state();

        let _ = mc.add_selection(rng(0, 10));

        let _ = mc.add_selection(rng(10, 20));

        assert_eq!(mc.len(), 1);

        assert_eq!(mc.selections[0].selection, Selection::Range(rng(0, 20)));

    }

    #[test]

    fn add_selection_disjoint_ranges_stay_separate() {

        let mut mc = empty_state();

        let _ = mc.add_selection(rng(0, 10));

        let _ = mc.add_selection(rng(11, 20));

        assert_eq!(mc.len(), 2);

        assert_sorted_nonoverlapping(&mc);

        assert_primary_resolves(&mc);

    }

    #[test]

    fn add_selection_reversed_range_is_normalized_for_merging() {

        // Backwards selection: start (20) is logically after end (5).

        let mut mc = empty_state();

        let _ = mc.add_selection(SelectionRange {

            start: c(20),

            end: c(5),

        });

        // A cursor *inside* the backwards range must merge with it.

        let _ = mc.add_cursor(c(10));

        assert_eq!(mc.len(), 1);

        // The merged result is normalized to a forwards range.

        assert_eq!(mc.selections[0].selection, Selection::Range(rng(5, 20)));

        assert_primary_resolves(&mc);

    }

    #[test]

    fn add_selection_at_u32_max_boundary_does_not_overflow() {

        let mut mc = empty_state();

        let _ = mc.add_selection(rng(u32::MAX - 1, u32::MAX));

        let _ = mc.add_cursor(c(u32::MAX));

        assert_eq!(mc.len(), 1);

        assert_eq!(

            mc.selections[0].selection,

            Selection::Range(rng(u32::MAX - 1, u32::MAX))

        );

        assert_primary_resolves(&mc);

    }

    #[test]

    fn add_cursor_stress_500_distinct_positions() {

        let mut mc = state(0);

        for i in 1..=500u32 {

            let _ = mc.add_cursor(c(i * 2));

        }

        assert_eq!(mc.len(), 501);

        assert_sorted_nonoverlapping(&mc);

        assert_primary_resolves(&mc);

        assert_ids_unique(&mc);

    }

    #[test]

    fn add_cursor_stress_same_position_never_grows() {

        let mut mc = state(9);

        for _ in 0..300 {

            let _ = mc.add_cursor(c(9));

        }

        assert_eq!(mc.len(), 1, "identical cursors must always collapse");

        assert_primary_resolves(&mc);

    }

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

    // remove_selection

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

    #[test]

    fn remove_selection_unknown_id_returns_false_and_changes_nothing() {

        let mut mc = state(1);

        let before = mc.clone();

        let ghost = SelectionId::new(); // never inserted anywhere

        assert!(!mc.remove_selection(ghost));

        assert_eq!(mc, before);

    }

    #[test]

    fn remove_selection_twice_second_call_returns_false() {

        let mut mc = state(0);

        let b = mc.add_cursor(c(10));

        assert!(mc.remove_selection(b));

        assert!(!mc.remove_selection(b));

        assert_eq!(mc.len(), 1);

        assert_primary_resolves(&mc);

    }

    #[test]

    fn remove_all_selections_leaves_a_safe_empty_state() {

        let mut mc = state(0);

        let b = mc.add_cursor(c(10));

        let a = mc.selections.iter().find(|s| s.id != b).unwrap().id;

        assert!(mc.remove_selection(a));

        assert!(mc.remove_selection(b));

        assert!(mc.is_empty());

        assert_eq!(mc.len(), 0);

        assert!(mc.get_primary().is_none());

        assert!(mc.get_primary_cursor().is_none());

        assert!(mc.to_selections().is_empty());

        // Further mutation of the empty state must not panic.

        mc.merge_overlapping();

        mc.move_all_cursors(true, |cur| *cur);

        assert!(mc.is_empty());

    }

    #[test]

    fn remove_primary_from_three_repoints_to_a_survivor() {

        let mut mc = state(0);

        let _ = mc.add_cursor(c(10));

        let p = mc.add_cursor(c(20)); // primary

        assert_eq!(mc.get_primary().unwrap().id, p);

        assert!(mc.remove_selection(p));

        assert_eq!(mc.len(), 2);

        assert_primary_resolves(&mc);

    }

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

    // get_primary / get_primary_mut / get_primary_cursor / to_selections / len

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

    #[test]

    fn empty_state_getters_return_none_without_panicking() {

        let mut mc = empty_state();

        assert!(mc.is_empty());

        assert_eq!(mc.len(), 0);

        assert!(mc.get_primary().is_none());

        assert!(mc.get_primary_mut().is_none());

        assert!(mc.get_primary_cursor().is_none());

        assert!(mc.to_selections().is_empty());

        mc.merge_overlapping(); // early-returns on len <= 1

        mc.ensure_primary_valid(); // private: must not panic on empty vec

        assert!(mc.is_empty());

    }

    #[test]

    fn get_primary_falls_back_to_last_when_primary_id_is_dangling() {

        let mut mc = state(0);

        let _ = mc.add_cursor(c(10));

        mc.primary_id = SelectionId::new(); // dangling: names nothing in the vec

        let p = mc.get_primary().expect("must fall back, not return None");

        assert_eq!(p.id, mc.selections.last().unwrap().id);

        assert_eq!(mc.get_primary_cursor(), Some(c(10)));

    }

    #[test]

    fn ensure_primary_valid_adopts_last_id_when_dangling() {

        let mut mc = state(0);

        let _ = mc.add_cursor(c(10));

        let dangling = SelectionId::new();

        mc.primary_id = dangling;

        mc.ensure_primary_valid();

        assert_ne!(mc.primary_id, dangling);

        assert_eq!(mc.primary_id, mc.selections.last().unwrap().id);

        // Idempotent: a second call on a now-valid id is a no-op.

        let fixed = mc.primary_id;

        mc.ensure_primary_valid();

        assert_eq!(mc.primary_id, fixed);

    }

    #[test]

    fn ensure_primary_valid_on_empty_leaves_id_untouched() {

        let mut mc = empty_state();

        let before = mc.primary_id;

        mc.ensure_primary_valid();

        assert_eq!(mc.primary_id, before, "nothing to adopt — id must not change");

        assert!(mc.get_primary().is_none());

    }

    #[test]

    fn get_primary_cursor_of_a_range_is_its_end_field() {

        let mut mc = empty_state();

        mc.set_single_range(rng(3, 9));

        assert_eq!(mc.get_primary_cursor(), Some(c(9)));

        // Backwards range: the raw `end` field is returned (the *focus*), even

        // though it is the lower position. This is deliberate — the caret sits

        // at the focus, not at the max boundary.

        let mut back = empty_state();

        back.set_single_range(SelectionRange {

            start: c(9),

            end: c(3),

        });