//! Timer callback information and utilities for azul-layout

//!

//! This module provides Timer, TimerCallbackInfo and related types for

//! managing timers that run on the main UI thread.

use core::ffi::c_void;

use azul_core::{

    callbacks::{TimerCallbackReturn, Update},

    dom::{DomId, OptionDomNodeId},

    geom::{LogicalPosition, LogicalSize, OptionLogicalPosition},

    id::NodeId,

    menu::Menu,

    refany::{OptionRefAny, RefAny},

    resources::ImageRef,

    task::{

        Duration, GetSystemTimeCallback, Instant, OptionDuration, OptionInstant, TerminateTimer,

        ThreadId, TimerId,

    },

    window::{KeyboardState, MouseState, WindowFlags},

};

use azul_css::AzString;

use crate::{

    callbacks::CallbackInfo,

    thread::Thread,

    window_state::{FullWindowState, WindowCreateOptions},

};

/// Default timer tick interval in milliseconds when no interval is configured.

const DEFAULT_TIMER_TICK_MS: u64 = 10;

/// Callback type for timers

pub type TimerCallbackType = extern "C" fn(

    /* timer internal refany */ RefAny,

    TimerCallbackInfo,

) -> TimerCallbackReturn;

/// Callback that runs on every frame on the main thread

#[repr(C)]

pub struct TimerCallback {

    pub cb: TimerCallbackType,

    /// For FFI: stores the foreign callable (e.g., `PyFunction`)

    /// Native Rust code sets this to None

    pub ctx: OptionRefAny,

}

impl TimerCallback {

}

impl core::fmt::Debug for TimerCallback {

}

impl Clone for TimerCallback {

}

impl From<TimerCallbackType> for TimerCallback {

}

impl PartialEq for TimerCallback {

}

impl Eq for TimerCallback {}

impl PartialOrd for TimerCallback {

}

impl Ord for TimerCallback {

}

impl core::hash::Hash for TimerCallback {

}

/// A `Timer` is a function that runs on every frame or at intervals.

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

#[repr(C)]

pub struct Timer {

    pub refany: RefAny,

    pub node_id: OptionDomNodeId,

    pub created: Instant,

    pub last_run: OptionInstant,

    pub run_count: usize,

    pub delay: OptionDuration,

    pub interval: OptionDuration,

    pub timeout: OptionDuration,

    pub callback: TimerCallback,

}

impl Timer {

    /// How often, in REAL milliseconds, the platform layer should wake to service

    /// this timer.

    ///

    /// A `Duration::Tick` interval is a FRAME count, so it is converted at the

    /// nominal frame rate rather than passed through. Passing it through treated

    /// one tick as one millisecond, so a `5t` interval asked the OS to wake ~16x

    /// more often than the timer could possibly fire — a measurable idle burn for

    /// a timer that flips at most every 5 frames.

        }

            }

        }

    #[inline]

    #[inline]

    #[inline]

    /// Invoke the timer callback and update internal state.

    ///

    /// Returns a `TimerCallbackReturn` with `DoNothing` + `Continue` if the timer

    /// is not ready to run yet (delay not elapsed for first run, or interval not

    /// elapsed for subsequent runs). Forces `Terminate` when the timeout expires.

        // Check if timer should run based on last_run, delay, and interval

                // Timer has run before - check interval

            }

            None => {

                // Timer has never run - check delay (first run)

            }

        }

        // Create a new TimerCallbackInfo wrapping the callback_info

        // CallbackInfo is Copy, so we can just copy it directly

        // Time THIS app callback under its own resolved symbol name

        // (`cb:my_timer_fn`): the per-phase histogram then compares one

        // callback's cost across versions, and a slow one is named in the

        // slow-span WARN. Resolution is cached; recording-off is one atomic.

}

impl Default for Timer {

        )

}

/// Information passed to timer callbacks.

///

/// This wraps `CallbackInfo` and adds timer-specific fields like `call_count` and `frame_start`.

/// `CallbackInfo` methods are available via explicit delegation methods below.

#[derive(Debug, Clone)]

#[repr(C)]

#[allow(clippy::pub_underscore_fields)] // _abi_ref/_abi_mut: intentional FFI/api.json ABI-stability placeholder fields

pub struct TimerCallbackInfo {

    pub callback_info: CallbackInfo,

    pub node_id: OptionDomNodeId,

    pub frame_start: Instant,

    pub call_count: usize,

    pub is_about_to_finish: bool,

    pub _abi_ref: *const c_void,

    pub _abi_mut: *mut c_void,

}

impl TimerCallbackInfo {

    // ==================== Delegated CallbackInfo methods ====================

    // These methods delegate to the inner callback_info to provide the same API

    // as CallbackInfo without using Deref (which causes issues with FFI codegen)

    /// Get the callable for FFI language bindings (Python, etc.)

    /// Add a timer to this window (applied after callback returns)

    /// Remove a timer from this window (applied after callback returns)

    /// Add a thread to this window (applied after callback returns)

    /// Remove a thread from this window (applied after callback returns)

    /// Stop event propagation (applied after callback returns)

    /// Create a new window (applied after callback returns)

    /// Close the current window (applied after callback returns)

    /// Modify the window state (applied after callback returns)

    /// Add an image to the image cache (applied after callback returns)

    /// Remove an image from the image cache (applied after callback returns)

    /// Re-render ALL image callbacks across all DOMs (applied after callback returns)

    ///

    /// This is the most efficient way to update animated GL textures from a timer.

    /// Triggers only texture re-rendering - no DOM rebuild or display list resubmission.

    /// Trigger re-rendering of a `VirtualView` (applied after callback returns)

    /// Reload system fonts (applied after callback returns)

    /// Prevent the default action

    /// Open a menu

    /// Open a menu at a specific position

    /// Show a tooltip at the current cursor position

    /// Show a tooltip at a specific position

    /// Hide the currently displayed tooltip

    /// Open a menu positioned relative to the currently hit node

    /// Get current window flags

    /// Get current keyboard state

    /// Get current mouse state

    /// Get the cursor position relative to the hit node

    /// Get the cursor position relative to the viewport

    /// Get the current cursor position

    /// Get the current time (when the timer callback started)

    /// Check if any node in a specific DOM is focused

    /// Check if pen is in contact

    /// Check if pen eraser is active

    /// Check if pen barrel button is pressed

    /// Check if dragging is active

    /// Check if drag is active

    /// Check if node drag is active

    /// Check if file drag is active

    /// Check if there's sufficient history for gestures

    // ==================== Scroll Management (timer architecture) ====================

    /// Get a read-only snapshot of a scroll node's bounds and position.

    ///

    /// Timer callbacks use this to read current scroll state for physics calculation.

    /// Find the closest scrollable ancestor of a node.

    ///

    /// Used by auto-scroll timer to find which container to scroll when

    /// the user drags beyond the container edge.

    /// Get the scroll input queue for consuming pending scroll inputs.

    ///

    /// The physics timer calls `take_all()` each tick to drain inputs

    /// recorded by platform event handlers.

    #[cfg(feature = "std")]

    /// Scroll a node to a specific position (via transactional `CallbackChange`).

    ///

    /// This is the primary way for timer callbacks to update scroll positions.

    /// The change is applied after the callback returns.

    /// Scroll to position without clamping (for rubber-banding/overscroll).

    // Cursor blink timer methods

    /// Set cursor visibility state (for cursor blink timer)

    /// Toggle cursor visibility (for cursor blink timer).

        use crate::callbacks::CallbackChange;

    /// Reset cursor blink state on user input

}

/// Optional Timer type for API compatibility

#[derive(Debug, Clone)]

#[repr(C, u8)]

// FFI Option enum; boxing the Some variant would break the #[repr(C, u8)] C ABI / api.json.

#[allow(variant_size_differences)] // repr(C,u8) FFI enum: boxing the large variant would change the C ABI (api.json bindings); size disparity accepted

#[allow(clippy::large_enum_variant)]

pub enum OptionTimer {

    None,

    Some(Timer),

}

impl From<Option<Timer>> for OptionTimer {

}

impl OptionTimer {

        }

}

#[cfg(all(test, feature = "std"))]

#[allow(

    clippy::float_cmp,

    clippy::too_many_lines,

    clippy::unreadable_literal,

    clippy::cognitive_complexity

)]

mod autotest_generated {

    use std::{

        collections::BTreeMap,

        sync::{

            atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering},

            Arc, Mutex, MutexGuard, PoisonError,

        },

    };

    use azul_core::{

        dom::DomNodeId,

        gl::OptionGlContextPtr,

        hit_test::ScrollPosition,

        menu::MenuItemVec,

        resources::{RawImageFormat, RendererResources},

        styled_dom::NodeHierarchyItemId,

        task::{SystemTick, SystemTickDiff, SystemTimeDiff, ThreadReceiver},

        window::{MonitorVec, RawWindowHandle},

    };

    use azul_css::system::SystemStyle;

    use rust_fontconfig::FcFontCache;

    use super::*;

    #[cfg(feature = "icu")]

    use crate::icu::IcuLocalizerHandle;

    use crate::{

        callbacks::{CallbackChange, CallbackInfoRefData, ExternalSystemCallbacks},

        thread::{ThreadCallbackType, ThreadSender},

        window::LayoutWindow,

    };

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

    // Time helpers

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

    /// A tick-based `Instant` — the only kind constructible without a real clock,

    /// and the only kind whose arithmetic is fully deterministic.

    fn tick(t: u64) -> Instant {

        Instant::Tick(SystemTick::new(t))

    }

    /// A tick-based `Duration`.

    const fn tick_dur(d: u64) -> Duration {

        Duration::Tick(SystemTickDiff { tick_diff: d })

    }

    /// A wall-clock-based `Duration` (deliberately the *wrong kind* to pair with

    /// a `Tick` instant — several tests below pin the saturating behaviour of

    /// exactly that mismatch).

    const fn sys_dur_millis(ms: u64) -> Duration {

        Duration::System(SystemTimeDiff::from_millis(ms))

    }

    /// Extract the tick counter, asserting the instant really is tick-based.

    fn tick_of(i: &Instant) -> u64 {

        match i {

            Instant::Tick(t) => t.tick_counter,

            Instant::System(_) => panic!("expected a Tick instant, got a System one"),

        }

    }

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

    // Fake clock + recording callback

    //

    // `GetSystemTimeCallbackType` is a bare `extern "C" fn()` with no context

    // pointer, so the fake clock has to live in statics. Every test that touches

    // them takes `clock_guard()` first, which serialises them against the rest of

    // the (parallel) test binary.

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

    static CLOCK_LOCK: Mutex<()> = Mutex::new(());

    static FAKE_TICK: AtomicU64 = AtomicU64::new(0);

    static CB_INVOCATIONS: AtomicUsize = AtomicUsize::new(0);

    static CB_SEEN_CALL_COUNT: AtomicUsize = AtomicUsize::new(0);

    static CB_SEEN_FRAME_START: AtomicU64 = AtomicU64::new(0);

    static CB_SEEN_ABOUT_TO_FINISH: AtomicBool = AtomicBool::new(false);

    static CB_RETURN_TERMINATE: AtomicBool = AtomicBool::new(false);

    /// Serialises access to the fake-clock / recorder statics. Ignores poisoning:

    /// a `#[should_panic]`-free suite still panics on assertion failure, and a

    /// poisoned lock must not cascade into unrelated test failures.

    fn clock_guard() -> MutexGuard<'static, ()> {

        let guard = CLOCK_LOCK.lock().unwrap_or_else(PoisonError::into_inner);

        FAKE_TICK.store(0, Ordering::SeqCst);

        CB_INVOCATIONS.store(0, Ordering::SeqCst);

        CB_SEEN_CALL_COUNT.store(0, Ordering::SeqCst);

        CB_SEEN_FRAME_START.store(0, Ordering::SeqCst);

        CB_SEEN_ABOUT_TO_FINISH.store(false, Ordering::SeqCst);

        CB_RETURN_TERMINATE.store(false, Ordering::SeqCst);

        guard

    }

    fn set_now(t: u64) {

        FAKE_TICK.store(t, Ordering::SeqCst);

    }

    extern "C" fn fake_clock() -> Instant {

        Instant::Tick(SystemTick::new(FAKE_TICK.load(Ordering::SeqCst)))

    }

    fn fake_clock_cb() -> GetSystemTimeCallback {

        GetSystemTimeCallback { cb: fake_clock }

    }

    /// Records everything the timer machinery handed it, and returns whatever

    /// `CB_RETURN_TERMINATE` currently says.

    extern "C" fn recording_cb(_data: RefAny, info: TimerCallbackInfo) -> TimerCallbackReturn {

        CB_INVOCATIONS.fetch_add(1, Ordering::SeqCst);

        CB_SEEN_CALL_COUNT.store(info.call_count, Ordering::SeqCst);

        CB_SEEN_ABOUT_TO_FINISH.store(info.is_about_to_finish, Ordering::SeqCst);

        if let Instant::Tick(t) = &info.frame_start {

            CB_SEEN_FRAME_START.store(t.tick_counter, Ordering::SeqCst);

        }

        TimerCallbackReturn {

            should_update: Update::DoNothing,

            should_terminate: if CB_RETURN_TERMINATE.load(Ordering::SeqCst) {

                TerminateTimer::Terminate

            } else {

                TerminateTimer::Continue

            },

        }

    }

    // Two callbacks with *different bodies* — identical bodies are legal prey for

    // identical-code folding, which would silently merge their addresses and make

    // the `TimerCallback` Eq/Ord/Hash tests below vacuous.

    extern "C" fn cb_alpha(_d: RefAny, _i: TimerCallbackInfo) -> TimerCallbackReturn {

        TimerCallbackReturn {

            should_update: Update::RefreshDom,

            should_terminate: TerminateTimer::Terminate,

        }

    }

    extern "C" fn cb_beta(_d: RefAny, _i: TimerCallbackInfo) -> TimerCallbackReturn {

        TimerCallbackReturn {

            should_update: Update::DoNothing,

            should_terminate: TerminateTimer::Continue,

        }

    }

    /// A timer created at tick `created`, driven by the fake clock.

    fn timer_at(created: u64, cb: TimerCallbackType) -> Timer {

        set_now(created);

        Timer::create(RefAny::new(0_usize), cb, fake_clock_cb())

    }

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

    // CallbackInfo harness (mirrors the one in `scroll_timer.rs`)

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

    struct Env<'a> {

        ref_data: &'a CallbackInfoRefData<'a>,

        changes: &'a Arc<Mutex<Vec<CallbackChange>>>,

    }

    impl Env<'_> {

        fn info(&self) -> CallbackInfo {

            self.info_with(OptionLogicalPosition::None, OptionLogicalPosition::None)

        }

        fn info_with(

            &self,

            cursor_relative_to_item: OptionLogicalPosition,

            cursor_in_viewport: OptionLogicalPosition,

        ) -> CallbackInfo {

            CallbackInfo::new(

                self.ref_data,

                self.changes,

                DomNodeId {

                    dom: DomId::ROOT_ID,

                    node: NodeHierarchyItemId::NONE,

                },

                cursor_relative_to_item,

                cursor_in_viewport,

            )

        }

        /// A `TimerCallbackInfo` with no attached node, frame_start = tick 0.

        fn timer_info(&self) -> TimerCallbackInfo {

            TimerCallbackInfo::create(self.info(), OptionDomNodeId::None, tick(0), 0, false)

        }

        fn take_changes(&self) -> Vec<CallbackChange> {

            self.changes

                .lock()

                .map(|mut c| core::mem::take(&mut *c))

                .unwrap_or_default()

        }

        /// Drain the log, asserting it holds exactly one change, and return it.

        fn take_one(&self) -> CallbackChange {

            let mut changes = self.take_changes();

            assert_eq!(changes.len(), 1, "expected exactly one change: {changes:?}");

            changes.remove(0)

        }

    }

    fn with_env<R>(f: impl FnOnce(&Env<'_>) -> R) -> R {

        with_env_cfg(false, OptionRefAny::None, f)

    }

    /// Builds a callback environment over an empty `LayoutWindow`. `left_down`

    /// drives the mouse state the drag predicates read; `ctx` is what `get_ctx`

    /// hands back to FFI bindings.

    fn with_env_cfg<R>(left_down: bool, ctx: OptionRefAny, f: impl FnOnce(&Env<'_>) -> R) -> R {

        let layout_window =

            LayoutWindow::new(FcFontCache::default()).expect("LayoutWindow::new failed");

        let renderer_resources = RendererResources::default();

        let previous_window_state: Option<FullWindowState> = None;

        let mut current_window_state = FullWindowState::default();

        current_window_state.mouse_state.left_down = left_down;

        let gl_context = OptionGlContextPtr::None;

        let scroll_states: BTreeMap<DomId, BTreeMap<NodeHierarchyItemId, ScrollPosition>> =

            BTreeMap::new();

        let window_handle = RawWindowHandle::Unsupported;

        let system_callbacks = ExternalSystemCallbacks::rust_internal();

        let ref_data = CallbackInfoRefData {

            layout_window: &layout_window,

            renderer_resources: &renderer_resources,

            previous_window_state: &previous_window_state,

            current_window_state: &current_window_state,

            gl_context: &gl_context,

            current_scroll_manager: &scroll_states,

            current_window_handle: &window_handle,

            system_callbacks: &system_callbacks,

            system_style: Arc::new(SystemStyle::default()),

            monitors: Arc::new(Mutex::new(MonitorVec::from_const_slice(&[]))),

            #[cfg(feature = "icu")]

            icu_localizer: IcuLocalizerHandle::default(),

            ctx,

        };

        let changes: Arc<Mutex<Vec<CallbackChange>>> = Arc::new(Mutex::new(Vec::new()));

        let env = Env {

            ref_data: &ref_data,

            changes: &changes,

        };

        f(&env)

    }

    fn empty_menu() -> Menu {

        Menu::create(MenuItemVec::from_const_slice(&[]))

    }

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

    // Timer::create / Default — constructor invariants

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

    #[test]

    fn timer_create_starts_completely_unarmed() {

        let _g = clock_guard();

        let t = timer_at(12_345, recording_cb as TimerCallbackType);

        assert_eq!(tick_of(&t.created), 12_345, "created must come from the clock");

        assert_eq!(t.run_count, 0);

        assert_eq!(t.last_run, OptionInstant::None);

        assert_eq!(t.delay, OptionDuration::None);

        assert_eq!(t.interval, OptionDuration::None);

        assert_eq!(t.timeout, OptionDuration::None);

        assert_eq!(t.node_id, OptionDomNodeId::None);

    }

    #[test]

    fn timer_create_at_max_tick_does_not_panic() {

        let _g = clock_guard();

        let t = timer_at(u64::MAX, recording_cb as TimerCallbackType);

        assert_eq!(tick_of(&t.created), u64::MAX);

        // Nothing is armed, so nothing can overflow off the end of time.

        assert!(!t.is_about_to_finish(&tick(u64::MAX)));

        assert_eq!(tick_of(&t.instant_of_next_run()), u64::MAX);

    }

    #[test]

    fn timer_default_is_a_zero_tick_timer() {

        let t = Timer::default();

        assert_eq!(tick_of(&t.created), 0);

        assert_eq!(t.run_count, 0);

        assert_eq!(t.last_run, OptionInstant::None);

        assert_eq!(t.tick_millis(), DEFAULT_TIMER_TICK_MS);

    }

    #[test]

    fn timer_clone_equals_original() {

        let _g = clock_guard();

        let t = timer_at(7, recording_cb as TimerCallbackType)

            .with_delay(tick_dur(1))

            .with_interval(tick_dur(2))

            .with_timeout(tick_dur(3));

        let c = t.clone();

        assert_eq!(t, c, "Clone must be value-preserving");

    }

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

    // Timer::tick_millis — numeric limits / round-trip

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

    #[test]

    fn tick_millis_falls_back_to_default_without_interval() {

        let _g = clock_guard();

        let t = timer_at(0, recording_cb as TimerCallbackType);

        assert_eq!(t.tick_millis(), DEFAULT_TIMER_TICK_MS);

        assert_eq!(t.tick_millis(), 10);

        // A delay/timeout must NOT be mistaken for an interval.

        let t = t.with_delay(tick_dur(999)).with_timeout(tick_dur(888));

        assert_eq!(t.tick_millis(), DEFAULT_TIMER_TICK_MS);

    }

    /// A tick interval is a FRAME count, so the platform wake-up interval it

    /// implies is `ticks / 60` seconds, not `ticks` milliseconds. The old

    /// pass-through made a `5t` timer ask the OS to wake every 5ms for a callback

    /// that can only fire every ~83ms.

    #[test]

    fn tick_millis_converts_tick_intervals_at_the_nominal_frame_rate() {

        let _g = clock_guard();

        for (raw, expected_ms) in [

            (0_u64, 0_u64),

            (1, 16),

            (5, 83),

            (60, 1_000),

            (600, 10_000),

        ] {

            let t = timer_at(0, recording_cb as TimerCallbackType).with_interval(tick_dur(raw));

            assert_eq!(

                t.tick_millis(),

                expected_ms,

                "a {raw}-tick interval is {expected_ms}ms of wall clock"

            );

        }

    }

    /// `u64::MAX` ticks is ~9.7 billion years, which does NOT fit in `u64`

    /// milliseconds. The conversion must clamp — wrapping would turn "never" into

    /// some small interval and busy-wake the event loop forever.

    #[test]

    fn tick_millis_saturates_on_an_absurd_tick_interval_instead_of_wrapping() {

        let _g = clock_guard();

        let t = timer_at(0, recording_cb as TimerCallbackType).with_interval(tick_dur(u64::MAX));

        assert_eq!(t.tick_millis(), u64::MAX);

        // The largest tick interval that still converts without clamping.

        let fits = u64::MAX / 1000 * 60;

        let t = timer_at(0, recording_cb as TimerCallbackType).with_interval(tick_dur(fits));

        assert!(t.tick_millis() < u64::MAX, "{fits} ticks should not clamp");

    }

    #[test]

    fn tick_millis_system_interval_round_trips_whole_millis() {

        let _g = clock_guard();

        // from_millis -> millis() is an exact round-trip, even at u64::MAX

        // (secs*1000 + 615 lands exactly on u64::MAX without saturating).

        for ms in [0_u64, 1, 999, 1_000, 1_001, 86_400_000, u64::MAX] {

            let t = timer_at(0, recording_cb as TimerCallbackType).with_interval(sys_dur_millis(ms));

            assert_eq!(t.tick_millis(), ms, "millis {ms} must round-trip");

        }

    }

    #[test]

    fn tick_millis_saturates_instead_of_overflowing() {

        let _g = clock_guard();

        // secs::MAX * 1000 overflows u64 — `millis()` must saturate, not panic.

        let huge = Duration::System(SystemTimeDiff {

            secs: u64::MAX,

            nanos: 999_999_999,

        });

        let t = timer_at(0, recording_cb as TimerCallbackType).with_interval(huge);

        assert_eq!(t.tick_millis(), u64::MAX);

    }

    #[test]

    fn tick_millis_truncates_sub_millisecond_intervals_to_zero() {

        let _g = clock_guard();

        // A 999_999ns interval is a *sub-millisecond* tick request; it truncates

        // to 0, i.e. "tick as fast as possible", not to 1.

        let t = timer_at(0, recording_cb as TimerCallbackType)

            .with_interval(Duration::System(SystemTimeDiff::from_nanos(999_999)));

        assert_eq!(t.tick_millis(), 0);

    }

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

    // Timer::is_about_to_finish — predicate boundaries

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

    #[test]

    fn is_about_to_finish_is_false_without_a_timeout() {

        let _g = clock_guard();

        let t = timer_at(0, recording_cb as TimerCallbackType);

        assert!(!t.is_about_to_finish(&tick(0)));

        assert!(!t.is_about_to_finish(&tick(u64::MAX)), "no timeout = never finishes");

    }

    #[test]

    fn is_about_to_finish_boundary_is_strictly_greater() {

        let _g = clock_guard();

        let t = timer_at(100, recording_cb as TimerCallbackType).with_timeout(tick_dur(50));

        assert!(!t.is_about_to_finish(&tick(149)), "1 tick early");

        // Elapsed == timeout is NOT "about to finish" — the comparison is `>`.

        assert!(!t.is_about_to_finish(&tick(150)), "exactly at the timeout");

        assert!(t.is_about_to_finish(&tick(151)), "1 tick past the timeout");

    }

    #[test]

    fn is_about_to_finish_saturates_when_the_clock_runs_backwards() {

        let _g = clock_guard();

        let t = timer_at(1_000, recording_cb as TimerCallbackType).with_timeout(tick_dur(10));

        // `now` older than `created`: duration_since saturates to 0 rather than

        // underflowing, so the timer is simply "not finished".

        assert!(!t.is_about_to_finish(&tick(0)));

    }

    #[test]

    fn is_about_to_finish_at_the_u64_ceiling() {

        let _g = clock_guard();

        let t = timer_at(0, recording_cb as TimerCallbackType);

        let max_timeout = t.clone().with_timeout(tick_dur(u64::MAX));

        assert!(

            !max_timeout.is_about_to_finish(&tick(u64::MAX)),

            "MAX elapsed is not > MAX timeout"

        );

        let near_max = t.with_timeout(tick_dur(u64::MAX - 1));

        assert!(near_max.is_about_to_finish(&tick(u64::MAX)));

    }

    /// A wall-clock timeout on a tick-driven timer must EXPIRE. `duration_since`

    /// yields a Tick duration, which is now compared against the System timeout

    /// on a canonical scale instead of saturating to `false`.

    ///

    /// The old saturating comparison made this timeout unexpirable — a timer

    /// created with a timeout silently became a timer with no timeout, and the

    /// only symptom was a callback that ran forever.

    #[test]

    fn is_about_to_finish_expires_a_wall_clock_timeout_on_a_tick_clock() {

        let _g = clock_guard();

        // 1ms at 60Hz is less than one frame, so the FIRST tick already exceeds it.

        let t = timer_at(0, recording_cb as TimerCallbackType).with_timeout(sys_dur_millis(1));

        assert!(!t.is_about_to_finish(&tick(0)), "no time has passed yet");

        assert!(t.is_about_to_finish(&tick(1)));

        assert!(t.is_about_to_finish(&tick(u64::MAX)));

        // A one-second timeout takes 60 whole frames, and expires strictly after.

        let t = timer_at(0, recording_cb as TimerCallbackType).with_timeout(sys_dur_millis(1_000));

        assert!(!t.is_about_to_finish(&tick(59)), "1 frame early");

        assert!(!t.is_about_to_finish(&tick(60)), "exactly at the timeout");

        assert!(t.is_about_to_finish(&tick(61)), "1 frame past the timeout");

    }

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

    // Timer::instant_of_next_run — getter invariants

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

    #[test]

    fn instant_of_next_run_is_created_when_nothing_is_armed() {

        let _g = clock_guard();

        let t = timer_at(42, recording_cb as TimerCallbackType);

        assert_eq!(tick_of(&t.instant_of_next_run()), 42);

    }

    #[test]

    fn instant_of_next_run_prefers_last_run_over_created() {

        let _g = clock_guard();

        let mut t = timer_at(100, recording_cb as TimerCallbackType).with_interval(tick_dur(7));

        assert_eq!(tick_of(&t.instant_of_next_run()), 107, "no run yet: created + interval");

        t.last_run = OptionInstant::Some(tick(500));

        assert_eq!(tick_of(&t.instant_of_next_run()), 507, "after a run: last_run + interval");

    }

    #[test]

    fn instant_of_next_run_sums_delay_and_interval() {

        let _g = clock_guard();

        // NOTE: when BOTH are set, the schedule point is `base + delay + interval`

        // — the delay is re-added on every subsequent run, even though `invoke`

        // only gates the *first* run on the delay. Pinned here as current

        // behaviour; see the report.

        let mut t = timer_at(100, recording_cb as TimerCallbackType)

            .with_delay(tick_dur(5))

            .with_interval(tick_dur(7));

        assert_eq!(tick_of(&t.instant_of_next_run()), 112);

        t.last_run = OptionInstant::Some(tick(200));

        assert_eq!(tick_of(&t.instant_of_next_run()), 212);

    }

    #[test]

    fn instant_of_next_run_saturates_at_the_end_of_time() {

        let _g = clock_guard();

        let t = timer_at(u64::MAX, recording_cb as TimerCallbackType)

            .with_delay(tick_dur(u64::MAX))

            .with_interval(tick_dur(u64::MAX));

        // Three MAXes added together: saturating_add, not an overflow panic.

        assert_eq!(tick_of(&t.instant_of_next_run()), u64::MAX);

    }

    /// System durations on a Tick instant are CONVERTED to whole frames, not

    /// dropped. Dropping them made `instant_of_next_run == created`, i.e. the

    /// timer claimed to be due immediately and stayed that way forever, which is

    /// how a unit mismatch turned into a scheduling bug with no error.

    #[test]

    fn instant_of_next_run_converts_wall_clock_delays_to_whole_frames() {

        let _g = clock_guard();

        let t = timer_at(42, recording_cb as TimerCallbackType)

            .with_delay(sys_dur_millis(1_000))

            .with_interval(sys_dur_millis(1_000));

        // 1000ms is 60 frames; delay + interval is 120.

        assert_eq!(tick_of(&t.instant_of_next_run()), 42 + 120);

    }

    /// A sub-frame wall-clock interval rounds DOWN to zero frames on a tick

    /// clock. That is the truthful answer at one-frame resolution — but it does

    /// mean such a timer is always due, so it is pinned here deliberately rather

    /// than rounded up to 1 to make something happen.

    #[test]

    fn instant_of_next_run_rounds_a_sub_frame_interval_down_to_zero_ticks() {

        let _g = clock_guard();

        let t = timer_at(42, recording_cb as TimerCallbackType).with_interval(sys_dur_millis(1));

        assert_eq!(tick_of(&t.instant_of_next_run()), 42);

    }

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

    // with_delay / with_interval / with_timeout — builder invariants

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

    #[test]

    fn with_setters_are_independent_and_preserve_the_rest() {

        let _g = clock_guard();

        let t = timer_at(9, recording_cb as TimerCallbackType)

            .with_delay(tick_dur(1))

            .with_interval(tick_dur(2))

            .with_timeout(tick_dur(3));

        assert_eq!(t.delay, OptionDuration::Some(tick_dur(1)));

        assert_eq!(t.interval, OptionDuration::Some(tick_dur(2)));

        assert_eq!(t.timeout, OptionDuration::Some(tick_dur(3)));

        // The builders must not disturb identity/progress fields.

        assert_eq!(tick_of(&t.created), 9);

        assert_eq!(t.run_count, 0);

        assert_eq!(t.last_run, OptionInstant::None);

    }

    #[test]

    fn with_setters_are_last_write_wins() {

        let _g = clock_guard();

        let t = timer_at(0, recording_cb as TimerCallbackType)

            .with_delay(tick_dur(1))

            .with_delay(tick_dur(2))

            .with_interval(tick_dur(3))

            .with_interval(tick_dur(4))

            .with_timeout(tick_dur(5))

            .with_timeout(tick_dur(6));

        assert_eq!(t.delay, OptionDuration::Some(tick_dur(2)));

        assert_eq!(t.interval, OptionDuration::Some(tick_dur(4)));

        assert_eq!(t.timeout, OptionDuration::Some(tick_dur(6)));

    }

    #[test]

    fn with_setters_accept_extreme_durations() {

        let _g = clock_guard();

        let t = timer_at(0, recording_cb as TimerCallbackType)

            .with_delay(tick_dur(0))

            .with_interval(tick_dur(u64::MAX))

            .with_timeout(Duration::max());

        assert_eq!(t.delay, OptionDuration::Some(tick_dur(0)));

        assert_eq!(t.tick_millis(), u64::MAX);

        // Duration::max() is a System duration -> never expires on a tick clock.

        assert!(!t.is_about_to_finish(&tick(u64::MAX)));

    }

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

    // TimerCallback — identity, ordering, hashing

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

    #[test]

    fn timer_callback_create_has_no_ffi_ctx() {

        let cb = TimerCallback::create(cb_alpha as TimerCallbackType);

        assert_eq!(cb.ctx, OptionRefAny::None);

        // `create` and the `From` impl must agree.

        let from: TimerCallback = (cb_alpha as TimerCallbackType).into();

        assert_eq!(cb, from);

    }

    #[test]

    fn timer_callback_identity_is_by_function_pointer() {

        let a1 = TimerCallback::create(cb_alpha as TimerCallbackType);

        let a2 = TimerCallback::create(cb_alpha as TimerCallbackType);

        let b = TimerCallback::create(cb_beta as TimerCallbackType);

        assert_eq!(a1, a2, "same fn -> equal");

        assert_ne!(a1, b, "different fn -> not equal");

        assert_eq!(a1, a1.clone(), "Clone preserves identity");

    }

    #[test]

    fn timer_callback_ord_and_hash_agree_with_eq() {

        use std::{

            collections::hash_map::DefaultHasher,

            hash::{Hash, Hasher},

        };

        fn hash_of(cb: &TimerCallback) -> u64 {

            let mut h = DefaultHasher::new();

            cb.hash(&mut h);

            h.finish()

        }

        let a = TimerCallback::create(cb_alpha as TimerCallbackType);

        let a2 = a.clone();

        let b = TimerCallback::create(cb_beta as TimerCallbackType);

        assert_eq!(a.cmp(&a2), core::cmp::Ordering::Equal);

        assert_eq!(hash_of(&a), hash_of(&a2), "Eq values must hash equal");

        // Ord must be antisymmetric and consistent with partial_cmp.

        assert_eq!(a.cmp(&b), a.partial_cmp(&b).unwrap());

        assert_eq!(a.cmp(&b).reverse(), b.cmp(&a));

        assert_ne!(a.cmp(&b), core::cmp::Ordering::Equal, "distinct fns must order strictly");

    }

    #[test]

    fn timer_callback_debug_does_not_panic() {

        let s = format!("{:?}", TimerCallback::create(cb_alpha as TimerCallbackType));

        assert!(s.starts_with("TimerCallback"), "got {s}");

    }

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

    // OptionTimer — round-trip

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

    #[test]

    fn option_timer_round_trips_both_variants() {

        let _g = clock_guard();

        assert!(OptionTimer::None.into_option().is_none());

        assert!(OptionTimer::from(None).into_option().is_none());

        let t = timer_at(3, recording_cb as TimerCallbackType).with_interval(tick_dur(4));

        let round_tripped = OptionTimer::from(Some(t.clone()))

            .into_option()

            .expect("Some must survive the round-trip");

        assert_eq!(round_tripped, t, "encode == decode");

    }

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

    // TimerCallbackInfo::create + getters

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

    #[test]

    fn timer_callback_info_create_preserves_extremes() {

        with_env(|env| {

            let info = TimerCallbackInfo::create(

                env.info(),

                OptionDomNodeId::None,

                tick(u64::MAX),

                usize::MAX,

                true,

            );

            assert_eq!(info.call_count, usize::MAX, "no wrap at usize::MAX");

            assert!(info.is_about_to_finish);

            assert_eq!(tick_of(&info.frame_start), u64::MAX);

            assert!(info._abi_ref.is_null());

            assert!(info._abi_mut.is_null());

            let zero =

                TimerCallbackInfo::create(env.info(), OptionDomNodeId::None, tick(0), 0, false);

            assert_eq!(zero.call_count, 0);

            assert!(!zero.is_about_to_finish);

            assert_eq!(tick_of(&zero.frame_start), 0);

        });

    }

    #[test]

    fn get_current_time_returns_frame_start_verbatim() {

        with_env(|env| {

            for t in [0_u64, 1, u64::MAX] {

                let info =

                    TimerCallbackInfo::create(env.info(), OptionDomNodeId::None, tick(t), 0, false);

                assert_eq!(info.get_current_time(), tick(t));

            }

        });

    }

    #[test]

    fn attached_node_queries_are_none_without_an_attached_node() {

        with_env(|env| {

            let info = env.timer_info();

            assert!(info.get_attached_node_size().is_none());

            assert!(info.get_attached_node_position().is_none());

        });

    }