//! Unified text editing manager

//!

//! Single source of truth for all text editing state. `MultiCursorState` is

//! the primary cursor/selection system. `BlinkState` handles the caret blink

//! animation. (Non-editable drag-select is not yet wired — the former

//! `SelectionManager` scaffolding was dead and has been removed; a future

//! implementation should build on `MultiCursorState`.)

//!

//! Every mutation that affects visual output sets `display_list_dirty = true`,

//! ensuring the display list is always regenerated.

use alloc::sync::Arc;

use core::sync::atomic::{AtomicBool, Ordering as AtomicOrdering};

use azul_core::{

    dom::{DomId, DomNodeId, NodeId},

    geom::LogicalRect,

    selection::{MultiCursorState, Selection, SelectionRange, TextCursor},

    styled_dom::NodeHierarchyItemId,

    task::{Duration, Instant},

};

/// Default cursor blink interval in milliseconds

pub const CURSOR_BLINK_INTERVAL_MS: u64 = 530;

/// Default cursor blink interval as a variant-agnostic [`Duration`].

///

/// The interval is a `Duration`, not a bare `u64` of milliseconds, so a

/// stylesheet can express it in the clockless `t` unit (`caret-animation-duration:

/// 5t`) and have it survive all the way to the comparison. `Duration`'s

/// comparisons are unit-aware, so a tick-unit interval and a wall-clock elapsed

/// value (or vice versa) still compare truthfully.

pub const CURSOR_BLINK_INTERVAL: Duration = Duration::from_millis(CURSOR_BLINK_INTERVAL_MS);

/// Cursor blink animation state.

///

/// Extracted from the old `CursorManager` so it can live independently

/// on `TextEditManager` without coupling to cursor position.

#[derive(Debug, Clone)]

pub struct BlinkState {

    /// Whether the cursor is currently visible (toggled by blink timer)

    pub is_visible: bool,

    /// Timestamp of the last user input event (keyboard, mouse click in text).

    /// Used to determine whether to blink or stay solid while typing.

    pub last_input_time: Option<Instant>,

    /// Whether the cursor blink timer is currently active

    pub blink_timer_active: bool,

    /// How long the caret stays solid after input before blinking resumes, and

    /// the interval the blink timer is armed with.

    ///

    /// Defaults to [`CURSOR_BLINK_INTERVAL`]; `caret-animation-duration` on the

    /// focused node overrides it, in whichever unit the stylesheet used.

    pub blink_interval: Duration,

}

impl Default for BlinkState {

}

impl BlinkState {

    /// Override the blink interval (from `caret-animation-duration`).

    ///

    /// Takes a [`Duration`] rather than milliseconds so a `t`-unit stylesheet

    /// value stays a frame count: a `5t` caret flips on the 5th frame exactly,

    /// on any machine, at any load.

    ///

    /// Prefer [`Self::adopt_blink_interval`] on a focus change: a RUNNING timer

    /// does not pick the new value up on its own.

    /// Adopt `interval`, reporting whether it actually CHANGED.

    ///

    /// The blink timer bakes the interval into the `Timer` once, at

    /// construction (`LayoutWindow::create_cursor_blink_timer`), so a timer

    /// that is already running keeps the PREVIOUS node's period no matter what

    /// this state says. Refocusing between two editables with different

    /// `caret-animation-duration` must therefore rebuild the timer — and only

    /// then, because rebuilding it on every focus change would restart the

    /// blink phase for nothing.

    ///

    /// This is the predicate that decides (see `HANDOFF-text-fix.md` for the

    /// `CursorBlinkTimerAction::Restart` half). A change of UNIT is a change:

    /// `5t` and `530ms` are different intervals, not one interval spelled two

    /// ways — the tick-unit caret must stay clockless.

    #[must_use]

    /// Reset blink on user input — cursor stays solid until blink interval elapses.

    /// Toggle cursor visibility (called by blink timer callback).

    /// Check if enough time has passed since last input to start blinking.

    ///

    /// The interval is [`Self::blink_interval`], compared unit-aware: a tick

    /// interval against wall-clock elapsed time (or the reverse) both answer

    /// truthfully. This used to build a `Duration::System` constant inline, which

    /// meant a tick-driven clock produced a `Duration::Tick` elapsed value that

    /// could never be "greater than" it — the caret stopped blinking, silently

    /// and permanently, on every clockless build.

    /// Clear all blink state (when editing ends).

    ///

    /// The interval goes back to the default too: it was read off the node that

    /// just lost focus, and leaving it behind would apply that node's

    /// `caret-animation-duration` to the next element focused — including one

    /// that never set the property.

}

/// One in-flight caret tween: the caret is gliding from `from` (what the

/// previous frame rendered) toward wherever the current layout puts it.

#[derive(Debug, Clone)]

pub struct CaretTweenTrack {

    /// Rect the tween starts from (the previously RENDERED rect, so a

    /// mid-flight retarget stays continuous).

    pub from: LogicalRect,

    /// Rect the tween is seeking. Retargeting happens ONLY when the layout's

    /// current rect stops matching this — comparing against the rendered

    /// rect would re-arm (and restart the clock) every animation tick.

    pub to: LogicalRect,

    /// When the tween (re)started.

    pub start: Instant,

}

/// One in-flight selection tween (same contract as [`CaretTweenTrack`],

/// for the whole selection band geometry).

#[derive(Debug, Clone)]

pub struct SelectionTweenTrack {

    pub from: Vec<LogicalRect>,

    /// Geometry the tween is seeking (same retarget contract as

    /// [`CaretTweenTrack::to`]).

    pub to: Vec<LogicalRect>,

    pub start: Instant,

}

/// Caret / selection tween bookkeeping, updated by the display-list

/// post-pass (`LayoutWindow::apply_text_tweens`). `tick_flag` is shared

/// with the tween timer's `RefAny` data so the timer can terminate itself

/// the tick after both tweens finish.

#[derive(Debug, Default)]

pub struct TextTweenState {

    /// DOM the tracked geometry belongs to. A caret/selection appearing on a

    /// DIFFERENT dom resets tracking (no cross-dom tween).

    pub dom_id: Option<DomId>,

    /// Node the tracked caret/selection geometry belongs to — the editing

    /// session's node, maintained by [`TextEditManager`].

    ///

    /// Without it the geometry is unattributable, and a DOM reconcile that

    /// moves or unmounts the edited node leaves `last_caret`/`last_selection`

    /// describing a rectangle that belongs to nothing: the next frame then

    /// glides the caret across the screen from a dead rect.

    pub node: Option<DomNodeId>,

    /// In-flight caret tween, if any.

    pub caret: Option<CaretTweenTrack>,

    /// Caret rect the last display-list pass RENDERED (tween target space).

    pub last_caret: Option<LogicalRect>,

    /// In-flight selection tween, if any.

    pub selection: Option<SelectionTweenTrack>,

    /// Selection rects the last display-list pass RENDERED.

    pub last_selection: Vec<LogicalRect>,

    /// In-flight focus-ring glide (ledger #29; opt-in via

    /// `SystemAnimations.focus_ring_duration_ms`).

    pub focus_ring: Option<CaretTweenTrack>,

    /// Focus-ring rect the last display-list pass RENDERED.

    pub last_focus_ring: Option<LogicalRect>,

    /// Shared "a tween is in flight" flag: written by the post-pass, read

    /// by `caret_tween_timer_callback` (via its `RefAny`) to self-terminate.

    pub tick_flag: Arc<AtomicBool>,

}

/// Cloning a manager must NOT share the original's tween-timer flag: the two

/// copies would steer one timer, and dropping either would tell that timer the

/// other's tweens had finished. So the flag is the ONE field that is not

/// shared — the clone gets its own `Arc` holding the same value. Everything

/// else is copied, because a `clone()` that quietly returned

/// `Self::default()` reported "no tween in flight, no rendered geometry" for a

/// manager that had both.

impl Clone for TextTweenState {

}

impl TextTweenState {

    /// True while any tween is mid-flight (drives the 16ms tween timer and

    /// forces the caret solid — blinking is suppressed during animation).

    /// Publish `is_active()` to the shared flag the tween timer polls.

    /// Reset all tracking (focus lost / editing cleared / dom switched).

    /// Reset only the TEXT tweens (caret + selection) — the focus ring has

    /// its own lifecycle (it runs without an editing session).

    ///

    /// `node` goes with them: it anchors the caret/selection geometry, not the

    /// ring.

}

/// The range selections of ONE editing session, as

/// [`TextEditManager::session_selection_ranges`] reports them.

///

/// All ranges of a session live on the same IFC root — `MultiCursorState` is

/// single-node by construction; a selection spanning several roots takes the

/// `cross_block` path instead.

#[derive(Debug, Clone, PartialEq)]

pub struct SessionSelectionRanges {

    /// DOM the session's node belongs to.

    pub dom_id: DomId,

    /// IFC root every range is expressed against.

    pub node_id: NodeId,

    /// Every range, in `MultiCursorState` order (position-sorted,

    /// non-overlapping). Never empty.

    pub ranges: Vec<SelectionRange>,

    /// The primary range: the most recently added one (Ctrl+D's newest

    /// occurrence), or the document-first range when the primary selection is

    /// a bare caret. Always an element of `ranges`.

    pub primary: SelectionRange,

}

/// Does `range` run FORWARD — anchor before focus in logical order?

///

/// `SelectionRange.start` is the ANCHOR and `.end` the FOCUS (the moving end:

/// `build_cursor_locations` reads the caret off `.end`), so a backward drag

/// arrives with `start > end`. This is the per-range form of the question

/// `LayoutWindow::set_cross_block_selection` answers for its node pair. A

/// degenerate range counts as forward, matching `TextSelection::new_collapsed`.

#[must_use]

/// Unified text editing manager.

///

/// `multi_cursor` is the single source of truth for cursor/selection positions.

/// `blink` manages the caret blink animation.

/// `SelectionManager` (sibling module) handles non-editable text drag-select.

#[derive(Debug, Clone)]

pub struct TextEditManager {

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

    /// `Some` whenever a contenteditable element has focus.

    /// Source of truth for `edit_text()` and display list painting.

    pub multi_cursor: Option<MultiCursorState>,

    /// Cross-block (multi-IFC-root) selection, render-ready. Precomputed by

    /// `LayoutWindow::set_cross_block_selection`; wins over `multi_cursor`

    /// in `build_text_selections_map` while set.

    pub cross_block: Option<azul_core::selection::TextSelection>,

    /// Cursor blink animation state.

    pub blink: BlinkState,

    /// IME preedit (composition) text currently being composed.

    /// Applies to the primary cursor only.

    pub preedit_text: Option<String>,

    /// Byte offset of cursor within preedit text (from IME), or -1 if unset.

    /// Uses -1 sentinel (rather than `Option`) to match platform IME C API conventions.

    pub preedit_cursor_begin: i32,

    /// Byte offset of cursor end within preedit text (from IME), or -1 if unset.

    /// Uses -1 sentinel (rather than `Option`) to match platform IME C API conventions.

    pub preedit_cursor_end: i32,

    /// Set to true by any mutation that changes visual output.

    pub display_list_dirty: bool,

    /// Caret / selection tween bookkeeping (see [`TextTweenState`]).

    pub tween: TextTweenState,

    /// Editing hosts whose text was mutated OUTSIDE the text-input record

    /// pipeline this pass (deletions, multi-cursor paste, the Enter line

    /// break). The host pass drains this and dispatches an `Input` event per

    /// host, so widget mirrors observe every committed edit, not only

    /// insertions. Filled by `LayoutWindow::record_text_edit_undo`.

    pub pending_edit_notifications: Vec<DomNodeId>,

}

impl Default for TextEditManager {

}

/// Only compares `multi_cursor` — blink state, preedit, and dirty flag are

/// transient visual state that should not affect logical equality of the

/// editing session.

impl PartialEq for TextEditManager {

}

impl TextEditManager {

    /// Create a new text edit manager with no active editing state

    // === Dirty flag ===

    /// Mark that the display list needs regeneration.

    // === Editing lifecycle ===

    /// Whether a contenteditable element is currently being edited.

    /// Get the `DomId` of the node being edited.

    /// Get the `NodeId` of the node being edited.

    /// Get the primary cursor position (last-added cursor).

    /// Whether the cursor should be drawn (editing active AND blink visible).

    /// Initialize editing for a newly focused contenteditable element.

    ///

    /// Creates a `MultiCursorState` with a single cursor, starts the blink,

    /// and sets preedit to None.

    ///

    /// # The caret is SOLID for the first half-period, not just "visible"

    ///

    /// This used to set `is_visible = true` and, in the same breath,

    /// `last_input_time = None`. Those two statements contradict each other:

    /// `None` is the "no input has EVER been recorded" encoding, for which

    /// [`BlinkState::should_blink`] is true immediately — so the blink timer's

    /// FIRST tick (a `Timer` with an interval and no delay runs on the first

    /// pump) toggled the freshly-shown caret straight back OFF. Clicking or

    /// tabbing into a field made the caret disappear on the next frame and only

    /// reappear a blink-interval later, which reads as a glitch and matches no

    /// other toolkit.

    ///

    /// It also made every caller responsible for repairing the state this

    /// method had just broken. Two of the three did:

    /// `LayoutWindow::handle_focus_change_for_cursor_blink` calls

    /// `reset_blink_on_input` BEFORE the deferred `finalize_pending_focus_changes`

    /// gets here (so its timestamp was overwritten with `None`), and

    /// `process_mouse_click_for_selection` calls it immediately AFTER (so its

    /// caret survived). The third, `process_accessibility_action`, did not — an

    /// AT-driven focus got the broken phase.

    ///

    /// `reset_blink_on_input(now)` sets BOTH halves consistently: caret shown

    /// AND the blink phase anchored at this instant, so `should_blink` stays

    /// false for `CURSOR_BLINK_INTERVAL_MS` and the first toggle happens one

    /// half-period after focus. That is the behaviour every other toolkit ships,

    /// and it makes the callers' own `reset_blink_on_input` calls redundant

    /// rather than load-bearing.

    ///

    /// `Instant::now()` honours the thread-scoped E2E test clock, so this stays

    /// deterministic under `tick_ms`.

        // The tween now tracks THIS node's caret. The previously rendered

        // geometry is kept on purpose — that is what makes the caret glide

        // from the field it left to the one it entered.

    /// End editing (focus left the contenteditable element).

        // Only ask for a repaint if there was something to erase.

        //

        // This used to mark dirty unconditionally, and it is reached on EVERY

        // focus change — including a Tab between two nodes that were never

        // editable. The manager then owed a repaint it had no pixels for, and

        // because `display_list_dirty` is a latch, one such focus move left the

        // window permanently "not idle": a permanent repaint request, on every

        // frame, for the rest of the window's life.

        //

        // Caught by the E2E non-interference gate, which saw `text_edit` move

        // on a focus-only step with the fingerprint otherwise identical —

        // cursor=none, preedit="" both before and after, and only `dirty`

        // flipping. Nothing changed, so nothing was owed.

    // === IME preedit ===

    /// Set the IME preedit (composition) text.

    /// Clear the IME preedit text (composition ended or cancelled).

    /// Clear the preedit, reporting whether anything was actually cleared.

    ///

    /// Split out so `clear_editing` can decide whether a repaint is owed

    /// without marking dirty twice — and so clearing an ALREADY-clear preedit

    /// costs nothing, which is the common case on a focus change.

    // === Convenience for building cursor_locations ===

    /// Build the Vec of cursor locations for `LayoutContext`.

    ///

    /// Returns all cursor positions from `MultiCursorState`, or empty if not editing.

        };

        };

            };

    /// Cross-block selection (spans multiple IFC roots), precomputed by

    /// `LayoutWindow::set_cross_block_selection` — the manager stores it

    /// render-ready because computing the per-IFC ranges needs layout/text

    /// access the manager does not have. Cleared by any single-node cursor

    /// interaction. When set, it wins over `multi_cursor` for rendering.

    /// Clear the cross-block selection (single-node interactions do this).

    /// Take the cross-block selection (delete/apply flows consume it).

    /// The active cross-block selection, if any.

    /// Every range selection of the current editing session.

    ///

    /// `None` when there is no session, the session's node is detached, or the

    /// session holds only bare carets — a collapsed caret is not a selection,

    /// so there is nothing to highlight.

    ///

    /// This is the COMPLETE selection data. `select_next_occurrence` (Ctrl+D)

    /// builds sessions with several ranges on one node, and the render-facing

    /// [`Self::build_text_selections_map`] can carry only one of them (see

    /// there); anything that needs all of them reads this.

    #[must_use]

        }

        // The primary selection can be a bare caret while other selections are

        // ranges (a multi-cursor click adds one; an edit can collapse the

        // primary range). The document-first range then stands in, so the

        // endpoints always describe a range that is actually painted.

    /// Build a `TextSelection` map for the display list's `paint_selections`.

    ///

    /// Extracts Range selections from `MultiCursorState` into the format that

    /// `LayoutContext.text_selections` expects: `BTreeMap<DomId, TextSelection>`.

    /// The `affected_nodes` map uses the editing node's `NodeId` as key.

    ///

    /// `anchor`, `focus` and `is_forward` all describe the SAME range — the

    /// session's primary, which is also one of the ranges in `affected_nodes`.

    /// They used to disagree: the endpoints came from the first range,

    /// `affected_nodes` kept the last (each insert overwrote the same key), and

    /// `is_forward` was hard-coded.

    ///

    /// `affected_nodes` carries EVERY range of the session under the one node

    /// key, so a multi-range (Ctrl+D) session paints all of its occurrences and

    /// not just the primary one.

        use azul_core::selection::{TextSelection, SelectionAnchor, SelectionFocus};

        };

}

impl crate::managers::NodeIdRemap for TextEditManager {

    /// Remap every node-keyed piece of editing state onto the rebuilt DOM: the

    /// multi-cursor session, the caret/selection tween geometry, the

    /// cross-block selection, and the queued edit notifications.

    ///

    /// `MultiCursorState::remap_node_ids` clears the selections when the edited

    /// node is gone; here we additionally drop the whole editing session, since a

    /// cursor whose IFC root no longer exists is not an editing session.

        // The tween's caret/selection geometry belongs to the session's node.

        // Resolve that anchor BEFORE the session below can be dropped — and

        // fall back to the session for state that was installed by writing

        // `multi_cursor` directly (which cannot set the anchor), so a stale

        // `None` heals itself here instead of leaving the geometry orphaned.

        // The tween follows its node, and dies with it: `last_caret` /

        // `last_selection` describe a rectangle that belonged to a node which

        // is now gone, and the next display-list pass would glide the caret

        // out of it across the screen.

            }

        // A cross-block selection is render-ready geometry keyed by IFC-root

        // NodeIds. Unremapped, it paints a highlight over whichever nodes

        // inherited those indices.

        // Queued `Input` notifications name the host they belong to; a host

        // that was unmounted has no event to dispatch, and keeping the id

        // would dispatch it at the node that took its place.

                }

}

impl TextEditManager {

    /// Rewrite the cross-block selection's IFC-root ids for the rebuilt DOM.

    ///

    /// The selection is dropped outright when either endpoint's root is gone:

    /// a band whose anchor or focus no longer exists has no endpoints to paint

    /// between. Interior roots that were unmounted are dropped individually.

        };

        ) else {

        };

        // Only owe a repaint when the painted band actually moved:

        // `display_list_dirty` is a latch, and a rebuild that renumbered

        // nothing has no pixels to redraw (see `clear_editing`).

}

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

// AUTOTEST: adversarial tests for `BlinkState` + `TextEditManager`

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

#[cfg(test)]

mod autotest_generated {

    use azul_core::{

        selection::{

            CursorAffinity, GraphemeClusterId, IdentifiedSelection, SelectionId, SelectionRange,

        },

        task::{Duration, SystemTick, SystemTimeDiff},

    };

    use super::*;

    use crate::managers::{NodeIdMap, NodeIdRemap};

    const DOM0: DomId = DomId { inner: 0 };

    const DOM1: DomId = DomId { inner: 1 };

    /// A `DomId` at the very top of the `usize` range — nothing indexes with it,

    /// so it must be carried through unchanged like any other id.

    const DOM_MAX: DomId = DomId { inner: usize::MAX };

    /// `NodeHierarchyItemId` stores nodes 1-based (`from_crate_internal` computes

    /// `index + 1`), so the largest node index that can survive a round-trip

    /// through a `DomNodeId` is `usize::MAX - 1`. `NodeId::new(usize::MAX)` is not

    /// representable and is deliberately never fed to `initialize_editing`.

    const MAX_ENCODABLE_NODE: usize = usize::MAX - 1;

    fn cursor(run: u32, byte: u32) -> TextCursor {

        TextCursor {

            cluster_id: GraphemeClusterId {

                source_run: run,

                start_byte_in_run: byte,

            },

            affinity: CursorAffinity::Leading,

        }

    }

    fn range(from: TextCursor, to: TextCursor) -> SelectionRange {

        SelectionRange {

            start: from,

            end: to,

        }

    }

    fn dom_node(dom: DomId, node: Option<NodeId>) -> DomNodeId {

        DomNodeId {

            dom,

            node: NodeHierarchyItemId::from_crate_internal(node),

        }

    }

    /// Build a `MultiCursorState` with an arbitrary selection list, bypassing

    /// `add_cursor`/`add_selection` (which sort + merge) so the exact ordering

    /// under test is preserved.

    fn multi_cursor_with(

        node_id: DomNodeId,

        selections: Vec<Selection>,

        key: u64,

    ) -> MultiCursorState {

        let identified: Vec<IdentifiedSelection> = selections

            .into_iter()

            .map(|selection| IdentifiedSelection {

                id: SelectionId::new(),

                selection,

            })

            .collect();

        let primary_id = identified

            .last()

            .map_or_else(SelectionId::new, |s| s.id);

        MultiCursorState {

            selections: identified,

            primary_id,

            node_id,

            contenteditable_key: key,

        }

    }

    /// `base + ms`, using the engine's own saturating instant arithmetic.

    fn plus_ms(base: &Instant, ms: u64) -> Instant {

        base.add_optional_duration(Some(&Duration::System(SystemTimeDiff::from_millis(ms))))

    }

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

    // BlinkState

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

    #[test]

    fn autotest_blink_new_invariants() {

        let b = BlinkState::new();

        assert!(!b.is_visible, "a fresh BlinkState starts hidden");

        assert!(b.last_input_time.is_none());

        assert!(!b.is_blink_timer_active());

        assert!(!b.blink_timer_active);

        // The default interval is the wall-clock one, so every existing caller

        // that never sets an interval keeps the 530ms behaviour it had.

        assert_eq!(b.blink_interval, CURSOR_BLINK_INTERVAL);

        assert_eq!(b.blink_interval, Duration::from_millis(CURSOR_BLINK_INTERVAL_MS));

        // No input has ever been recorded, so blinking is allowed immediately.

        assert!(b.should_blink(&Instant::now()));

    }

    #[test]

    fn autotest_blink_toggle_visibility_alternates_and_returns_new_state() {

        let mut b = BlinkState::new();

        assert!(b.toggle_visibility(), "first toggle turns the caret on");

        assert!(b.is_visible);

        assert!(!b.toggle_visibility(), "second toggle turns it back off");

        assert!(!b.is_visible);

        // 1000 toggles: the return value must always equal the new field value,

        // and parity must be exactly preserved (no drift, no panic).

        let mut expected = false;

        for _ in 0..1000 {

            expected = !expected;

            let returned = b.toggle_visibility();

            assert_eq!(returned, expected);

            assert_eq!(b.is_visible, expected);

        }

        assert!(!b.is_visible, "an even number of toggles restores the state");

    }

    #[test]

    fn autotest_blink_set_visibility_is_idempotent_and_orthogonal() {

        let mut b = BlinkState::new();

        b.set_blink_timer_active(true);

        b.set_visibility(true);

        b.set_visibility(true);

        assert!(b.is_visible);

        assert!(

            b.is_blink_timer_active(),

            "visibility must not disturb the timer flag"

        );

        b.set_visibility(false);

        b.set_visibility(false);

        assert!(!b.is_visible);

        assert!(b.is_blink_timer_active());

    }

    #[test]

    fn autotest_blink_timer_active_true_false_and_idempotent() {

        let mut b = BlinkState::new();

        assert!(!b.is_blink_timer_active(), "known-false: default state");

        b.set_blink_timer_active(true);

        assert!(b.is_blink_timer_active(), "known-true: after activation");

        b.set_blink_timer_active(true);

        assert!(b.is_blink_timer_active(), "re-activation is idempotent");

        b.set_blink_timer_active(false);

        assert!(!b.is_blink_timer_active());

        b.set_blink_timer_active(false);

        assert!(!b.is_blink_timer_active(), "re-deactivation is idempotent");

        // The timer flag never leaks into visibility.

        assert!(!b.is_visible);

    }

    #[test]

    fn autotest_blink_reset_on_input_forces_solid_caret() {

        let mut b = BlinkState::new();

        b.set_blink_timer_active(true);

        b.set_visibility(false);

        let now = Instant::now();

        b.reset_blink_on_input(now.clone());

        assert!(b.is_visible, "typing must show a solid caret");

        assert_eq!(b.last_input_time.as_ref(), Some(&now));

        assert!(

            b.is_blink_timer_active(),

            "reset_blink_on_input must not stop the timer"

        );

        // Immediately after input, the blink interval has not elapsed.

        assert!(!b.should_blink(&now));

    }

    #[test]

    fn autotest_blink_reset_on_input_repeated_keeps_latest_timestamp() {

        let mut b = BlinkState::new();

        let base = Instant::now();

        // Simulate a fast typist: 500 keystrokes, 1ms apart.

        for i in 0..500u64 {

            b.reset_blink_on_input(plus_ms(&base, i));

            assert!(b.is_visible, "the caret stays solid throughout typing");

        }

        let last = plus_ms(&base, 499);

        assert_eq!(b.last_input_time.as_ref(), Some(&last));

        // The whole burst spans 499ms < 530ms, so blinking has still not resumed.

        assert!(!b.should_blink(&last));

    }

    #[test]

    fn autotest_blink_should_blink_without_input_is_true() {

        let b = BlinkState::new();

        let now = Instant::now();

        assert!(b.should_blink(&now));

        // Also true for an instant far in the past — no input means no gate at all.

        assert!(b.should_blink(&Instant::Tick(SystemTick::new(0))));

    }

    #[test]

    fn autotest_blink_should_blink_interval_boundary_is_strict() {

        let base = Instant::now();

        let mut b = BlinkState::new();

        b.reset_blink_on_input(base.clone());

        assert!(

            !b.should_blink(&base),

            "zero elapsed time must not restart the blink"

        );

        assert!(

            !b.should_blink(&plus_ms(&base, CURSOR_BLINK_INTERVAL_MS - 1)),

            "one millisecond before the interval: still solid"

        );

        assert!(

            !b.should_blink(&plus_ms(&base, CURSOR_BLINK_INTERVAL_MS)),

            "exactly at the interval: the comparison is strictly greater-than"

        );

        assert!(

            b.should_blink(&plus_ms(&base, CURSOR_BLINK_INTERVAL_MS + 1)),

            "one millisecond past the interval: blinking resumes"

        );

        // Far past the interval (one day) — no overflow, still blinking.

        assert!(b.should_blink(&plus_ms(&base, 86_400_000)));

    }

    #[test]

    fn autotest_blink_should_blink_reversed_clock_saturates_to_false() {

        // `now` is *earlier* than the recorded input (clock skew / reordered

        // events). `Instant::duration_since` saturates to zero rather than

        // panicking, so the caret stays solid instead of the call blowing up.

        let base = Instant::now();

        let mut b = BlinkState::new();

        b.reset_blink_on_input(plus_ms(&base, 10_000));

        assert!(!b.should_blink(&base));

        assert!(b.is_visible);

    }

    #[test]

    fn autotest_blink_should_blink_mismatched_instant_kinds_are_deterministic() {

        // A Tick instant compared against a System instant has no meaningful

        // span: the two counters have no common origin, so `duration_since`

        // saturates to `Duration::Tick(0)` and nothing is ever "elapsed".

        // (This is about mismatched INSTANTS, which really are incomparable —

        // unlike mismatched DURATIONS, which are just two units of the same

        // thing and now convert.)

        let mut b = BlinkState::new();

        b.reset_blink_on_input(Instant::now());

        let tick_now = Instant::Tick(SystemTick::new(u64::MAX));

        assert_eq!(b.should_blink(&tick_now), b.should_blink(&tick_now));

        assert!(!b.should_blink(&tick_now));

    }

    /// A tick-only clock (no_std, or any clockless build) MUST resume blinking.

    ///

    /// Both endpoints are Tick, so the elapsed span is a `Duration::Tick`, which

    /// is compared against the wall-clock-typed blink interval on a canonical

    /// scale. Before that comparison was unit-aware, the answer was `false`

    /// forever and the caret on a clockless build simply never blinked again.

    #[test]

    fn autotest_blink_a_tick_only_clock_resumes_blinking_at_the_exact_frame() {

        let mut t = BlinkState::new();

        t.reset_blink_on_input(Instant::Tick(SystemTick::new(0)));

        // 530ms is 31.8 frames at 60Hz, so frame 31 is early and frame 32 blinks.

        assert!(!t.should_blink(&Instant::Tick(SystemTick::new(31))));

        assert!(t.should_blink(&Instant::Tick(SystemTick::new(32))));

        assert!(t.should_blink(&Instant::Tick(SystemTick::new(u64::MAX))));

    }

    /// The whole point of the `t` unit: a blink interval expressed in FRAMES

    /// flips on exactly the Nth frame — frame N-1 is solid, frame N blinks.

    /// There is no rounding, no clock, and nothing for a slow machine to shift.

    #[test]

    fn autotest_blink_a_tick_interval_flips_on_exactly_the_nth_frame() {

        let mut b = BlinkState::new();

        b.set_blink_interval(Duration::from_ticks(5));

        b.reset_blink_on_input(Instant::Tick(SystemTick::new(100)));

        for frame in 100..=105 {

            assert!(

                !b.should_blink(&Instant::Tick(SystemTick::new(frame))),

                "frame {frame} is within 5 frames of the input and must stay solid"

            );

        }

        assert!(

            b.should_blink(&Instant::Tick(SystemTick::new(106))),

            "frame 106 is strictly more than 5 frames past the input"

        );

    }

    /// The same tick interval, driven off a WALL-CLOCK instant: 5 frames is

    /// 83.33ms, so 83ms is solid and 84ms blinks. A `5t` stylesheet value

    /// therefore behaves identically on a desktop shell and on a clockless one.

    #[test]

    fn autotest_blink_a_tick_interval_converts_on_a_wall_clock_instant() {

        let base = Instant::now();

        let mut b = BlinkState::new();

        b.set_blink_interval(Duration::from_ticks(5));

        b.reset_blink_on_input(base.clone());

        assert!(!b.should_blink(&plus_ms(&base, 83)));

        assert!(b.should_blink(&plus_ms(&base, 84)));

    }

    /// The refocus predicate: a running blink timer holds the interval it was

    /// BUILT with, so the only safe trigger for rebuilding it is "the value

    /// actually changed". Same value ⇒ false (never restart the blink phase for

    /// nothing); different value — including a different UNIT — ⇒ true.

    #[test]

    fn autotest_blink_adopt_interval_reports_only_real_changes() {

        let mut b = BlinkState::new();

        assert!(

            !b.adopt_blink_interval(CURSOR_BLINK_INTERVAL),

            "the default adopted again is not a change"

        );

        assert!(b.adopt_blink_interval(Duration::from_millis(250)));

        assert_eq!(b.blink_interval, Duration::from_millis(250));

        assert!(

            !b.adopt_blink_interval(Duration::from_millis(250)),

            "idempotent: refocusing a node with the SAME duration must not restart the timer"

        );

        // 5 frames is 83.33ms, and 83ms is not 5 frames: the unit is part of

        // the value, so switching between them is a real change.

        assert!(b.adopt_blink_interval(Duration::from_ticks(5)));

        assert!(b.adopt_blink_interval(Duration::from_millis(83)));

        assert!(b.adopt_blink_interval(Duration::from_ticks(5)));

        assert_eq!(b.blink_interval, Duration::from_ticks(5));

        // `clear()` puts the default back, so the next focus on a node with an

        // explicit duration sees a change and rebuilds.

        b.clear();

        assert!(b.adopt_blink_interval(Duration::from_ticks(5)));

    }

    #[test]

    fn autotest_blink_clear_resets_every_field_and_is_idempotent() {

        let mut b = BlinkState::new();

        b.reset_blink_on_input(Instant::now());

        b.set_blink_timer_active(true);

        b.set_blink_interval(Duration::from_ticks(5));

        b.clear();

        assert!(!b.is_visible);

        assert!(b.last_input_time.is_none());

        assert!(!b.is_blink_timer_active());

        assert_eq!(

            b.blink_interval, CURSOR_BLINK_INTERVAL,

            "the previous node's caret-animation-duration must not leak to the next"

        );

        // Clearing an already-cleared state must not panic or resurrect anything.

        b.clear();

        assert!(!b.is_visible);

        assert!(b.last_input_time.is_none());

        assert!(!b.is_blink_timer_active());

        // With no last input, blinking is unblocked again.

        assert!(b.should_blink(&Instant::now()));

    }

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

    // TextEditManager — construction / predicates / getters

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

    #[test]

    fn autotest_manager_new_invariants() {

        let m = TextEditManager::new();

        assert!(m.multi_cursor.is_none());

        assert!(!m.has_active_editing());

        assert!(m.get_editing_dom_id().is_none());

        assert!(m.get_editing_node_id().is_none());

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

        assert!(!m.should_draw_cursor());

        assert!(m.preedit_text.is_none());

        assert_eq!(m.preedit_cursor_begin, -1, "-1 is the 'unset' IME sentinel");

        assert_eq!(m.preedit_cursor_end, -1);

        assert!(!m.display_list_dirty, "a fresh manager owes no repaint");

        assert!(m.build_cursor_locations().is_empty());

        assert!(m.build_text_selections_map().is_empty());

        assert_eq!(m, TextEditManager::default());

    }

    #[test]

    fn autotest_manager_mark_dirty_is_sticky() {

        let mut m = TextEditManager::new();

        m.mark_dirty();

        assert!(m.display_list_dirty);

        m.mark_dirty();

        assert!(m.display_list_dirty, "marking twice must not toggle it off");

    }

    #[test]

    fn autotest_manager_partial_eq_ignores_transient_state() {

        // Documented contract: only `multi_cursor` participates in equality.

        let mut a = TextEditManager::new();

        let mut b = TextEditManager::new();

        assert_eq!(a, b);

        a.set_preedit("か".to_string(), 0, 3);

        a.blink.set_visibility(true);

        a.mark_dirty();

        assert_eq!(a, b, "preedit / blink / dirty are transient visual state");

        b.initialize_editing(cursor(0, 0), DOM0, NodeId::ZERO, 1);

        assert_ne!(a, b, "a live editing session is not equal to no session");

    }

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

    // TextEditManager — initialize_editing (numeric edges)

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

    #[test]

    fn autotest_initialize_editing_at_zero() {

        let mut m = TextEditManager::new();

        m.initialize_editing(cursor(0, 0), DOM0, NodeId::ZERO, 0);

        assert!(m.has_active_editing());

        assert_eq!(m.get_editing_dom_id(), Some(DOM0));

        assert_eq!(

            m.get_editing_node_id(),

            Some(NodeId::ZERO),

            "node index 0 must not be confused with the 'no node' encoding"

        );

        assert_eq!(m.get_primary_cursor(), Some(cursor(0, 0)));

        assert_eq!(

            m.multi_cursor.as_ref().map(|mc| mc.contenteditable_key),

            Some(0)

        );

        assert!(m.blink.is_visible);

        // The caret is SOLID for the first half-period after focus, so the blink

        // phase must be ANCHORED here. `None` would mean "no input ever", for

        // which `should_blink` is true immediately and the timer's first tick

        // hides the caret the user just placed. See `initialize_editing`.

        let anchored = m

            .blink

            .last_input_time

            .as_ref()

            .expect("initialize_editing must anchor the blink phase, not clear it");

        assert!(

            !m.blink.should_blink(anchored),

            "at the instant of focus, zero time has elapsed — blinking must not be allowed yet"

        );

        assert!(m.should_draw_cursor());

        assert!(m.display_list_dirty);

        assert_eq!(

            m.build_cursor_locations(),

            vec![(DOM0, NodeId::ZERO, cursor(0, 0))]

        );

    }

    #[test]

    fn autotest_initialize_editing_at_integer_extremes() {

        // Max representable node index, max DomId, max contenteditable key, and a

        // cursor at the top of the u32 grapheme-coordinate space.

        let node = NodeId::new(MAX_ENCODABLE_NODE);

        let extreme_cursor = TextCursor {

            cluster_id: GraphemeClusterId {

                source_run: u32::MAX,

                start_byte_in_run: u32::MAX,

            },

            affinity: CursorAffinity::Trailing,

        };

        let mut m = TextEditManager::new();

        m.initialize_editing(extreme_cursor, DOM_MAX, node, u64::MAX);

        assert_eq!(m.get_editing_dom_id(), Some(DOM_MAX));

        assert_eq!(

            m.get_editing_node_id(),

            Some(node),

            "usize::MAX - 1 is the largest 1-based-encodable node index"

        );

        assert_eq!(m.get_primary_cursor(), Some(extreme_cursor));

        assert_eq!(

            m.multi_cursor.as_ref().map(|mc| mc.contenteditable_key),

            Some(u64::MAX),

            "the contenteditable key is opaque — u64::MAX must survive verbatim"

        );

        assert_eq!(

            m.build_cursor_locations(),

            vec![(DOM_MAX, node, extreme_cursor)]

        );

    }

    #[test]

    fn autotest_initialize_editing_overwrites_previous_session() {

        let mut m = TextEditManager::new();

        m.initialize_editing(cursor(1, 1), DOM0, NodeId::new(7), 111);

        m.initialize_editing(cursor(2, 2), DOM1, NodeId::new(9), 222);

        assert_eq!(m.get_editing_dom_id(), Some(DOM1));

        assert_eq!(m.get_editing_node_id(), Some(NodeId::new(9)));

        assert_eq!(m.get_primary_cursor(), Some(cursor(2, 2)));

        assert_eq!(

            m.build_cursor_locations().len(),

            1,

            "re-initializing replaces the cursor set, it does not accumulate"

        );

        assert_eq!(

            m.multi_cursor.as_ref().map(|mc| mc.contenteditable_key),

            Some(222)

        );

    }

    #[test]

    fn autotest_initialize_editing_clears_stale_preedit() {

        let mut m = TextEditManager::new();

        m.set_preedit("漢字".to_string(), 3, 6);

        m.initialize_editing(cursor(0, 0), DOM0, NodeId::new(4), 42);

        assert!(

            m.preedit_text.is_none(),

            "focusing a new element must drop the old composition"

        );

        assert_eq!(m.preedit_cursor_begin, -1);

        assert_eq!(m.preedit_cursor_end, -1);

    }

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

    // TextEditManager — clear_editing

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

    #[test]

    fn autotest_clear_editing_on_fresh_manager_is_safe() {