//! Callback handling for layout events

//!

//! This module provides the CallbackInfo struct and related types for handling

//! UI callbacks. Callbacks need access to layout information (node sizes, positions,

//! hierarchy), which is why this module lives in azul-layout instead of azul-core.

// Re-export callback macro from azul-core

use alloc::{

    boxed::Box,

    collections::{btree_map::BTreeMap, VecDeque},

    sync::Arc,

    vec::Vec,

};

#[cfg(feature = "std")]

use std::sync::Mutex;

use azul_core::{

    animation::UpdateImageType,

    callbacks::{CoreCallback, FocusTarget, FocusTargetPath, HidpiAdjustedBounds, Update},

    dom::{DomId, DomIdVec, DomNodeId, IdOrClass, NodeId, NodeType},

    geom::{LogicalPosition, LogicalRect, LogicalSize, OptionLogicalPosition, OptionCursorNodePosition, OptionScreenPosition, OptionDragDelta, CursorNodePosition, ScreenPosition, DragDelta},

    gl::OptionGlContextPtr,

    gpu::GpuValueCache,

    hit_test::ScrollPosition,

    id::NodeId as CoreNodeId,

    impl_callback,

    menu::Menu,

    refany::{OptionRefAny, RefAny},

    resources::{ImageCache, ImageMask, ImageRef, LoadedFont, LoadedFontVec, RendererResources},

    selection::{Selection, SelectionRange, SelectionRangeVec, SelectionState, TextCursor},

    styled_dom::{NodeHierarchyItemId, NodeHierarchyItemIdVec, StyledDom},

    task::{self, GetSystemTimeCallback, Instant, ThreadId, ThreadIdVec, TimerId, TimerIdVec},

    window::{KeyboardState, Monitor, MonitorVec, MouseState, OptionMonitor, RawWindowHandle, WindowFlags, WindowSize},

    FastBTreeSet, OrderedMap,

};

use azul_css::{

    css::CssPath,

    props::{

        basic::FontRef,

        property::{CssProperty, CssPropertyType, CssPropertyVec},

    },

    system::SystemStyle,

    AzString, OptionU8Vec, StringVec, U8Vec,

};

use rust_fontconfig::FcFontCache;

#[cfg(feature = "icu")]

use crate::icu::{

    FormatLength, IcuDate, IcuDateTime, IcuLocalizerHandle, IcuResult,

    IcuStringVec, IcuTime, ListType, PluralCategory,

};

use crate::{

    hit_test::FullHitTest,

    managers::{

        drag_drop::DragDropManager,

        file_drop::FileDropManager,

        focus_cursor::FocusManager,

        gesture::{GestureAndDragManager, InputSample, PenState},

        gpu_state::GpuStateManager,

        hover::{HoverManager, InputPointId},

        virtual_view::VirtualViewManager,

        scroll_state::{AnimatedScrollState, ScrollManager},

        selection::ClipboardContent,

        text_input::{PendingTextEdit, TextInputManager},

        undo_redo::{UndoRedoManager, UndoableOperation},

    },

    text3::cache::{TextShapingCache as TextLayoutCache, UnifiedLayout},

    thread::{CreateThreadCallback, Thread},

    timer::Timer,

    window::{DomLayoutResult, LayoutWindow},

    window_state::{FullWindowState, WindowCreateOptions},

};

use azul_css::{impl_option, impl_option_inner};

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

// FFI-safe wrapper types for tuple returns

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

/// FFI-safe wrapper for pen tilt angles (x_tilt, y_tilt) in degrees

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

#[repr(C)]

pub struct PenTilt {

    /// X-axis tilt angle in degrees (-90 to 90)

    pub x_tilt: f32,

    /// Y-axis tilt angle in degrees (-90 to 90)

    pub y_tilt: f32,

}

impl From<(f32, f32)> for PenTilt {

}

impl_option!(

    PenTilt,

    OptionPenTilt,

    [Debug, Clone, Copy, PartialEq, PartialOrd]

);

/// FFI-safe wrapper for select-all result (full_text, selected_range)

#[derive(Debug, Clone, PartialEq)]

#[repr(C)]

pub struct SelectAllResult {

    /// The full text content of the node

    pub full_text: AzString,

    /// The range that would be selected

    pub selection_range: SelectionRange,

}

impl From<(alloc::string::String, SelectionRange)> for SelectAllResult {

}

impl_option!(

    SelectAllResult,

    OptionSelectAllResult,

    copy = false,

    [Debug, Clone, PartialEq]

);

/// FFI-safe wrapper for delete inspection result (range_to_delete, deleted_text)

#[derive(Debug, Clone, PartialEq)]

#[repr(C)]

pub struct DeleteResult {

    /// The range that would be deleted

    pub range_to_delete: SelectionRange,

    /// The text that would be deleted

    pub deleted_text: AzString,

}

impl From<(SelectionRange, alloc::string::String)> for DeleteResult {

}

impl_option!(

    DeleteResult,

    OptionDeleteResult,

    copy = false,

    [Debug, Clone, PartialEq]

);

/// Represents a change made by a callback that will be applied after the callback returns

///

/// This transaction-based system provides:

/// - Clear separation between read-only queries and modifications

/// - Atomic application of all changes

/// - Easy debugging and logging of callback actions

/// - Future extensibility for new change types

#[derive(Debug, Clone)]

pub enum CallbackChange {

    // Window State Changes

    /// Modify the window state (size, position, title, etc.)

    ModifyWindowState { state: FullWindowState },

    /// Inject a platform-native gesture-recognizer result into the

    /// in-process `GestureAndDragManager`. Read by the next

    /// `detect_long_press` / `detect_swipe_direction` / `detect_pinch` /

    /// `detect_rotation` / `detect_double_click` call, then cleared.

    InjectNativeGesture {

        gesture: crate::managers::gesture::NativeGestureEvent,

    },

    /// Queue multiple window state changes to be applied in sequence across frames.

    /// This is needed for simulating clicks (mouse down -> wait -> mouse up) where each

    /// state change needs to trigger separate event processing.

    QueueWindowStateSequence { states: Vec<FullWindowState> },

    /// Create a new window

    CreateNewWindow { options: WindowCreateOptions },

    /// Close the current window (via Update::CloseWindow return value, tracked here for logging)

    CloseWindow,

    // Focus Management

    /// Change keyboard focus to a specific node or clear focus

    SetFocusTarget { target: FocusTarget },

    // Event Propagation Control

    /// Stop event from propagating to parent nodes (W3C stopPropagation).

    /// Remaining handlers on the *current* node still fire, but no handlers

    /// on ancestor / descendant nodes in subsequent phases.

    StopPropagation,

    /// Stop event propagation immediately (W3C stopImmediatePropagation).

    /// No further handlers fire - not even remaining handlers on the same node.

    StopImmediatePropagation,

    /// Prevent default browser behavior (e.g., block text input from being applied)

    PreventDefault,

    // Timer Management

    /// Add a new timer to the window

    AddTimer { timer_id: TimerId, timer: Timer },

    /// Remove an existing timer

    RemoveTimer { timer_id: TimerId },

    // Thread Management

    /// Add a new background thread

    AddThread { thread_id: ThreadId, thread: Thread },

    /// Remove an existing thread

    RemoveThread { thread_id: ThreadId },

    // Content Modifications

    /// Change the text content of a node

    ChangeNodeText { node_id: DomNodeId, text: AzString },

    /// Change the image of a node

    ChangeNodeImage {

        dom_id: DomId,

        node_id: NodeId,

        image: ImageRef,

        update_type: UpdateImageType,

    },

    /// Re-render an image callback (for resize/animation)

    /// This triggers re-invocation of the RenderImageCallback

    UpdateImageCallback { dom_id: DomId, node_id: NodeId },

    /// Re-render ALL image callbacks across all DOMs.

    ///

    /// This is the most efficient way to update animated GL textures:

    /// it triggers only texture re-rendering without DOM rebuild or

    /// display list resubmission. Used by timer callbacks that need

    /// to update OpenGL textures every frame.

    UpdateAllImageCallbacks,

    /// Trigger re-rendering of a VirtualView with a new DOM

    /// This forces the VirtualView to call its callback and update the display list

    UpdateVirtualView { dom_id: DomId, node_id: NodeId },

    /// Change the image mask of a node

    ChangeNodeImageMask {

        dom_id: DomId,

        node_id: NodeId,

        mask: ImageMask,

    },

    /// Change CSS properties of a node

    ChangeNodeCssProperties {

        dom_id: DomId,

        node_id: NodeId,

        properties: CssPropertyVec,

    },

    /// Override CSS properties on a node via the user-override channel

    /// (`CssPropertyCache::user_overridden_properties`). Unlike

    /// `ChangeNodeCssProperties`, this does not mutate the node's static

    /// `css_props` - the override layer is read at higher priority by the

    /// property resolution pipeline, so animating a handful of properties

    /// per frame stays cheap. Passing `CssProperty::Initial` for a property

    /// removes any prior override for that type on the same node.

    OverrideNodeCssProperties {

        dom_id: DomId,

        node_id: NodeId,

        properties: CssPropertyVec,

    },

    // Scroll Management

    /// Scroll a node to a specific position

    ScrollTo {

        dom_id: DomId,

        node_id: NodeHierarchyItemId,

        position: LogicalPosition,

        /// When true, skip clamping to [0, max_scroll] bounds.

        /// Used by the scroll physics timer for rubber-banding/overscroll.

        unclamped: bool,

    },

    /// Scroll a node into view (W3C scrollIntoView API)

    /// The scroll adjustments are calculated and applied when the change is processed

    ScrollIntoView {

        node_id: DomNodeId,

        options: crate::managers::scroll_into_view::ScrollIntoViewOptions,

    },

    // Image Cache Management

    /// Add an image to the image cache

    AddImageToCache { id: AzString, image: ImageRef },

    /// Remove an image from the image cache

    RemoveImageFromCache { id: AzString },

    // Font Cache Management

    /// Reload system fonts (expensive operation)

    ReloadSystemFonts,

    // Menu Management

    /// Open a context menu or dropdown menu

    /// Whether it's native or fallback depends on window.state.flags.use_native_context_menus

    OpenMenu {

        menu: Menu,

        /// Optional position override (if None, uses menu.position)

        position: Option<LogicalPosition>,

    },

    // Tooltip Management

    /// Show a tooltip at a specific position

    ///

    /// Platform-specific implementation:

    /// - Windows: Uses native tooltip window (TOOLTIPS_CLASS)

    /// - macOS: Uses NSPopover or custom NSWindow with tooltip styling

    /// - X11: Creates transient window with _NET_WM_WINDOW_TYPE_TOOLTIP

    /// - Wayland: Creates surface with zwlr_layer_shell_v1 (overlay layer)

    ShowTooltip {

        text: AzString,

        position: LogicalPosition,

    },

    /// Hide the currently displayed tooltip

    HideTooltip,

    // Text Editing

    /// Insert text at the current cursor position or replace selection

    InsertText {

        dom_id: DomId,

        node_id: NodeId,

        text: AzString,

    },

    /// Delete text backward (backspace) at cursor

    DeleteBackward { dom_id: DomId, node_id: NodeId },

    /// Delete text forward (delete key) at cursor

    DeleteForward { dom_id: DomId, node_id: NodeId },

    /// Move cursor to a specific position

    MoveCursor {

        dom_id: DomId,

        node_id: NodeId,

        cursor: TextCursor,

    },

    /// Set text selection range

    SetSelection {

        dom_id: DomId,

        node_id: NodeId,

        selection: Selection,

    },

    /// Set/override the text changeset for the current text input operation

    /// This allows callbacks to modify what text will be inserted during text input events

    SetTextChangeset { changeset: PendingTextEdit },

    // Cursor Movement Operations

    /// Move cursor left (arrow left)

    MoveCursorLeft {

        dom_id: DomId,

        node_id: NodeId,

        extend_selection: bool,

    },

    /// Move cursor right (arrow right)

    MoveCursorRight {

        dom_id: DomId,

        node_id: NodeId,

        extend_selection: bool,

    },

    /// Move cursor up (arrow up)

    MoveCursorUp {

        dom_id: DomId,

        node_id: NodeId,

        extend_selection: bool,

    },

    /// Move cursor down (arrow down)

    MoveCursorDown {

        dom_id: DomId,

        node_id: NodeId,

        extend_selection: bool,

    },

    /// Move cursor to line start (Home key)

    MoveCursorToLineStart {

        dom_id: DomId,

        node_id: NodeId,

        extend_selection: bool,

    },

    /// Move cursor to line end (End key)

    MoveCursorToLineEnd {

        dom_id: DomId,

        node_id: NodeId,

        extend_selection: bool,

    },

    /// Move cursor to document start (Ctrl+Home)

    MoveCursorToDocumentStart {

        dom_id: DomId,

        node_id: NodeId,

        extend_selection: bool,

    },

    /// Move cursor to document end (Ctrl+End)

    MoveCursorToDocumentEnd {

        dom_id: DomId,

        node_id: NodeId,

        extend_selection: bool,

    },

    // Multi-Cursor Operations

    /// Add an additional cursor at the specified position (Ctrl+Click from C API)

    AddCursor {

        dom_id: DomId,

        node_id: NodeId,

        cursor: TextCursor,

    },

    /// Add an additional selection range (for multi-cursor)

    AddSelectionRange {

        dom_id: DomId,

        node_id: NodeId,

        range: SelectionRange,

    },

    /// Remove a specific selection by its stable ID

    RemoveSelectionById {

        selection_id: azul_core::selection::SelectionId,

    },

    // Clipboard Operations (Override)

    /// Override clipboard content for copy operation

    SetCopyContent {

        target: DomNodeId,

        content: ClipboardContent,

    },

    /// Override clipboard content for cut operation

    SetCutContent {

        target: DomNodeId,

        content: ClipboardContent,

    },

    /// Override selection range for select-all operation

    SetSelectAllRange {

        target: DomNodeId,

        range: SelectionRange,

    },

    // Hit Test Request (for Debug API)

    /// Request a hit test update at a specific position

    ///

    /// This is used by the Debug API to update the hover manager's hit test

    /// data after modifying the mouse position, ensuring that callbacks

    /// can find the correct nodes under the cursor.

    RequestHitTestUpdate { position: LogicalPosition },

    // Text Selection (for Debug API)

    /// Process a text selection click at a specific position

    ///

    /// This is used by the Debug API to trigger text selection directly,

    /// bypassing the normal event pipeline. The handler will:

    /// 1. Hit-test IFC roots to find selectable text at the position

    /// 2. Create a text cursor at the clicked position

    /// 3. Update the selection manager with the new selection

    ProcessTextSelectionClick {

        position: LogicalPosition,

        time_ms: u64,

    },

    // Cursor Blinking (System Timer Control)

    /// Set the cursor visibility state (called by blink timer)

    SetCursorVisibility { visible: bool },

    /// Reset cursor blink state on user input (makes cursor visible, records time)

    ResetCursorBlink,

    /// Start the cursor blink timer for the focused contenteditable element

    StartCursorBlinkTimer,

    /// Stop the cursor blink timer (when focus leaves contenteditable)

    StopCursorBlinkTimer,

    // Scroll cursor/selection into view

    /// Scroll the active text cursor into view within its scrollable container

    /// This is automatically triggered after text input or cursor movement

    ScrollActiveCursorIntoView,

    // Create Text Input Event (for Debug API / Programmatic Text Input)

    /// Create a synthetic text input event

    ///

    /// This simulates receiving text input from the OS. The text input flow will:

    /// 1. Record the text in TextInputManager (creating a PendingTextEdit)

    /// 2. Generate synthetic TextInput events

    /// 3. Invoke user callbacks (which can intercept/reject via preventDefault)

    /// 4. Apply the changeset if not rejected

    /// 5. Mark dirty nodes for re-render

    CreateTextInput {

        /// The text to insert

        text: AzString,

    },

    // Window Move (Compositor-Managed)

    /// Request the compositor to begin an interactive window move.

    /// On Wayland: calls xdg_toplevel_move(toplevel, seat, serial).

    /// On other platforms: this is a no-op (use set_window_position instead).

    BeginInteractiveMove,

    // Drag-and-Drop Data Transfer

    /// Set drag data for a MIME type (W3C: dataTransfer.setData)

    /// Should be called in a DragStart callback to populate the drag data.

    SetDragData {

        mime_type: AzString,

        data: Vec<u8>,

    },

    /// Accept the current drop on this target (W3C: event.preventDefault() in DragOver)

    /// Must be called from a DragOver or DragEnter callback for the Drop event to fire.

    AcceptDrop,

    /// Set the drop effect (W3C: dataTransfer.dropEffect)

    SetDropEffect {

        effect: azul_core::drag::DropEffect,

    },

    // DOM Mutation (for Debug API)

    /// Insert a new child node into the DOM tree.

    /// Creates a minimal StyledDom from the given node_type and appends it

    /// as a child of parent_node_id. If position is Some, inserts at that

    /// child index; otherwise appends at the end.

    InsertChildNode {

        dom_id: DomId,

        parent_node_id: NodeId,

        /// The tag/type of the new node (e.g. "div", "p", "text:Hello")

        node_type_str: AzString,

        /// Optional child index to insert at (None = append at end)

        position: Option<usize>,

        /// Optional CSS classes for the new node

        classes: Vec<AzString>,

        /// Optional ID for the new node

        id: Option<AzString>,

    },

    /// Delete a node from the DOM tree (and all its children).

    /// The node is "tombstoned" (set to an empty anonymous Div) rather than

    /// physically removed, to preserve node ID stability.

    DeleteNode {

        dom_id: DomId,

        node_id: NodeId,

    },

    /// Set the IDs and classes on an existing node.

    SetNodeIdsAndClasses {

        dom_id: DomId,

        node_id: NodeId,

        ids_and_classes: azul_core::dom::IdOrClassVec,

    },

    // Routing

    /// Switch to a different route.

    ///

    /// On desktop: swaps `FullWindowState.layout_callback` to the matched

    /// route's callback, stores the `RouteMatch`, and triggers `RefreshDom`.

    /// On web: additionally calls `history.pushState()`.

    SwitchRoute {

        /// Route pattern to switch to (e.g. `"/user/:id"`)

        pattern: AzString,

        /// Route parameters (e.g. `[("id", "42")]`)

        params: azul_core::window::StringPairVec,

    },

}

/// Main callback type for UI event handling

pub type CallbackType = extern "C" fn(RefAny, CallbackInfo) -> Update;

/// Stores a function pointer that is executed when the given UI element is hit

///

/// Must return an `Update` that denotes if the screen should be redrawn.

#[repr(C)]

pub struct Callback {

    pub cb: CallbackType,

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

    /// Native Rust code sets this to None

    pub ctx: OptionRefAny,

}

impl_callback!(Callback, CallbackType);

// Host-invoker plumbing for managed-FFI bindings (Lua, Ruby, Perl, ...).

// See `azul_core::host_invoker` for the design. This expands to a static

// `az_callback_thunk` that the framework dispatches by-value args to, an

// `AzCallback_createFromHostHandle` C-ABI export the host calls per

// `set_on_click(...)` site, plus the `AzApp_setCallbackInvoker` setter the

// host calls once at module load to register its libffi closure.

azul_core::impl_managed_callback! {

    wrapper:        Callback,

    info_ty:        CallbackInfo,

    return_ty:      Update,

    default_ret:    Update::DoNothing,

    invoker_static: CALLBACK_INVOKER,

    invoker_ty:     AzCallbackInvoker,

    thunk_fn:       az_callback_thunk,

    setter_fn:      AzApp_setCallbackInvoker,

    from_handle_fn: AzCallback_createFromHostHandle,

}

impl Callback {

    /// Create a new callback with just a function pointer (for native Rust code)

    /// Convert from CoreCallback (stored as usize) to Callback (actual function pointer)

    ///

    /// Preserves `ctx` so that callbacks registered via the host-invoker path

    /// (e.g. `Callback::create_from_host_handle`) keep their host-handle ctx

    /// across the dispatch cycle. Without this, `info.get_ctx()` inside the

    /// generated thunk would see `OptionRefAny::None` and bail out with the

    /// kind's default value - which makes managed-FFI click handlers

    /// silently no-op.

    ///

    /// # Safety

    /// The caller must ensure that the usize in CoreCallback.cb was originally a valid

    /// function pointer of type `CallbackType`. This is guaranteed when CoreCallback

    /// is created through standard APIs, but unsafe code could violate this.

    /// Convert to CoreCallback (function pointer stored as usize)

    ///

    /// This is always safe - we're just casting the function pointer to usize for storage.

}

/// Allow Callback to be passed to functions expecting `C: Into<CoreCallback>`

impl From<Callback> for CoreCallback {

}

impl Callback {

    /// Safely invoke the callback with the given data and info

    ///

    /// This is a safe wrapper around calling the function pointer directly.

}

/// FFI-safe Option<Callback> type for C interop.

///

/// This enum provides an ABI-stable alternative to `Option<Callback>`

/// that can be safely passed across FFI boundaries.

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

#[repr(C, u8)]

pub enum OptionCallback {

    /// No callback is present.

    None,

    /// A callback is present.

    Some(Callback),

}

impl OptionCallback {

    /// Converts this FFI-safe option into a standard Rust `Option<Callback>`.

        }

    /// Returns `true` if a callback is present.

    /// Returns `true` if no callback is present.

}

impl From<Option<Callback>> for OptionCallback {

        }

}

impl From<OptionCallback> for Option<Callback> {

}

/// Information about the callback that is passed to the callback whenever a callback is invoked

///

/// # Architecture

///

/// CallbackInfo uses a transaction-based system:

/// - **Read-only pointers**: Access to layout data, window state, managers for queries

/// - **Change vector**: All modifications are recorded as CallbackChange items

/// - **Processing**: Changes are applied atomically after callback returns

///

/// This design provides clear separation between queries and modifications, makes debugging

/// easier, and allows for future extensibility.

/// Reference data container for CallbackInfo (all read-only fields)

///

/// This struct consolidates all readonly references that callbacks need to query window state.

/// By grouping these into a single struct, we reduce the number of parameters to

/// CallbackInfo::new() from 13 to 3, making the API more maintainable and easier to extend.

///

/// This is pure syntax sugar - the struct lives on the stack in the caller and is passed by

/// reference.

pub struct CallbackInfoRefData<'a> {

    /// Pointer to the LayoutWindow containing all layout results (READ-ONLY for queries)

    pub layout_window: &'a LayoutWindow,

    /// Necessary to query FontRefs from callbacks

    pub renderer_resources: &'a RendererResources,

    /// Previous window state (for detecting changes)

    pub previous_window_state: &'a Option<FullWindowState>,

    /// State of the current window that the callback was called on (read only!)

    pub current_window_state: &'a FullWindowState,

    /// An Rc to the OpenGL context, in order to be able to render to OpenGL textures

    pub gl_context: &'a OptionGlContextPtr,

    /// Immutable reference to where the nodes are currently scrolled (current position)

    pub current_scroll_manager: &'a BTreeMap<DomId, BTreeMap<NodeHierarchyItemId, ScrollPosition>>,

    /// Handle of the current window

    pub current_window_handle: &'a RawWindowHandle,

    /// Callbacks for creating threads and getting the system time (since this crate uses no_std)

    pub system_callbacks: &'a ExternalSystemCallbacks,

    /// Platform-specific system style (colors, spacing, etc.)

    /// Arc allows safe cloning in callbacks without unsafe pointer manipulation

    pub system_style: Arc<SystemStyle>,

    /// Shared monitor list - initialized once at app start, updated by the platform

    /// layer on monitor topology changes (e.g. WM_DISPLAYCHANGE, NSScreenParametersChanged).

    /// Callbacks lock the mutex to read; platform locks to write.

    pub monitors: Arc<Mutex<MonitorVec>>,

    /// ICU4X localizer cache for internationalized formatting (numbers, dates, lists, plurals)

    /// Caches localizers for multiple locales. Only available when the "icu" feature is enabled.

    #[cfg(feature = "icu")]

    pub icu_localizer: IcuLocalizerHandle,

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

    /// Cloned from the Callback struct before invocation. Native Rust callbacks have this as None.

    pub ctx: OptionRefAny,

}

/// CallbackInfo is a lightweight wrapper around pointers to stack-local data.

/// It can be safely copied because it only contains pointers - the underlying

/// data lives on the stack and outlives the callback invocation.

/// This allows callbacks to "consume" CallbackInfo by value while the caller

/// retains access to the same underlying data.

///

/// The `changes` field uses a pointer to Arc<Mutex<...>> so that cloned CallbackInfo instances

/// (e.g., passed to timer callbacks) still push changes to the original collection,

/// while keeping CallbackInfo as Copy.

#[derive(Debug, Clone, Copy)]

#[repr(C)]

pub struct CallbackInfo {

    // Read-only Data (Query Access)

    /// Single reference to all readonly reference data

    /// This consolidates 8 individual parameters into 1, improving API ergonomics

    ref_data: *const CallbackInfoRefData<'static>,

    // Context Info (Immutable Event Data)

    /// The ID of the DOM + the node that was hit

    hit_dom_node: DomNodeId,

    /// The (x, y) position of the mouse cursor, **relative to top left of the element that was

    /// hit**

    cursor_relative_to_item: OptionLogicalPosition,

    /// The (x, y) position of the mouse cursor, **relative to top left of the window**

    cursor_in_viewport: OptionLogicalPosition,

    // Transaction Container (New System) - Uses pointer to Arc<Mutex> for shared access across clones

    /// All changes made by the callback, applied atomically after callback returns

    /// Stored as raw pointer so CallbackInfo remains Copy

    #[cfg(feature = "std")]

    changes: *const Arc<Mutex<Vec<CallbackChange>>>,

    #[cfg(not(feature = "std"))]

    changes: *mut Vec<CallbackChange>,

}

impl CallbackInfo {

    #[cfg(feature = "std")]

    #[cfg(not(feature = "std"))]

    pub fn new<'a>(

        ref_data: &'a CallbackInfoRefData<'a>,

        changes: &'a mut Vec<CallbackChange>,

        hit_dom_node: DomNodeId,

        cursor_relative_to_item: OptionLogicalPosition,

        cursor_in_viewport: OptionLogicalPosition,

    ) -> Self {

        Self {

            // SAFETY: pointer cast only - erases lifetime 'a to 'static.

            ref_data: ref_data as *const CallbackInfoRefData<'a> as *const CallbackInfoRefData<'static>,

            hit_dom_node,

            cursor_relative_to_item,

            cursor_in_viewport,

            changes: changes as *mut Vec<CallbackChange>,

        }

    }

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

    ///

    /// Returns the cloned OptionRefAny if a callable was set, or None if this

    /// is a native Rust callback.

    /// Returns the OpenGL context if available

    // Helper methods for transaction system

    /// Push a change to be applied after the callback returns

    /// This is the primary method for modifying window state from callbacks

    #[cfg(feature = "std")]

        // SAFETY: The pointer is valid for the lifetime of the callback

        unsafe {

        }

    #[cfg(not(feature = "std"))]

    pub fn push_change(&mut self, change: CallbackChange) {

        unsafe { (*self.changes).push(change) }

    }

    /// Debug helper to get the changes pointer for debugging

    #[cfg(feature = "std")]

    /// Get the collected changes (consumes them from the Arc<Mutex>)

    #[cfg(feature = "std")]

        // SAFETY: The pointer is valid for the lifetime of the callback

        unsafe {

            } else {

            }

        }

    #[cfg(not(feature = "std"))]

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

        unsafe { core::mem::take(&mut *self.changes) }

    }

    /// Check if pending changes require relayout before the next step.

    ///

    /// Returns true for `ModifyWindowState` (resize) and `ScrollTo` (scroll),

    /// which both need the event loop to re-run layout so that subsequent

    /// operations (like `take_screenshot`) see updated content.

    ///

    /// Used by the E2E test runner to detect when it needs to yield.

    #[cfg(feature = "std")]

        unsafe {

                    CallbackChange::ModifyWindowState { .. } |

                    CallbackChange::ScrollTo { .. }

                ))

            } else {

            }

        }

    // Modern Api (using CallbackChange transactions)

    /// 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)

    ///

    /// W3C `stopPropagation()`: remaining handlers on the *current* node

    /// still fire, but no handlers on ancestor/descendant nodes are called.

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

    ///

    /// W3C `stopImmediatePropagation()`: no further handlers fire,

    /// not even remaining handlers registered on the same node.

    /// Set keyboard focus target (applied after callback returns)

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

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

    /// Switch to a different route (applied after callback returns).

    ///

    /// On desktop: swaps the layout callback and triggers `RefreshDom`.

    /// On web: also calls `history.pushState()`.

    ///

    /// # C API

    /// ```c

    /// AzCallbackInfo_switchRoute(&info, AzString_fromConstStr("/user/:id"),

    ///     AzStringPairVec_fromConstSlice(&[AzStringPair { key: "id", value: "42" }]));

    /// ```

    /// Get the current active route pattern (e.g. `"/user/:id"`).

    ///

    /// Returns empty string if no route is active.

    ///

    /// # C API

    /// ```c

    /// AzString pattern = AzCallbackInfo_getRoutePattern(&info);

    /// ```

        }

    /// Get a route parameter by key (e.g. `"id"` from `/user/:id`).

    ///

    /// Returns empty string if the parameter doesn't exist or no route is active.

    ///

    /// # C API

    /// ```c

    /// AzString id = AzCallbackInfo_getRouteParam(&info, AzString_fromConstStr("id"));

    /// ```

            }

        }

    /// Set a route parameter value and trigger re-render.

    ///

    /// This modifies the active route's params in-place and triggers a DOM refresh.

    /// On web, this also updates the URL via `history.replaceState()`.

    ///

    /// # C API

    /// ```c

    /// AzCallbackInfo_setRouteParam(&info, AzString_fromConstStr("id"), AzString_fromConstStr("99"));

    /// ```

        };

            }

        };

        // Update or insert the parameter

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

    /// Request the compositor to begin an interactive window move.

    ///

    /// On Wayland: calls `xdg_toplevel_move(toplevel, seat, serial)` which lets

    /// the compositor handle the move. This is the only way to move windows on Wayland.

    /// On other platforms: this is a no-op; use `modify_window_state()` to set position.

    /// Queue multiple window state changes to be applied in sequence.

    /// Each state triggers a separate event processing cycle, which is needed

    /// for simulating clicks where mouse down and mouse up must be separate events.

    /// Change the text content of a node (applied after callback returns)

    ///

    /// This method was previously called `set_string_contents` in older API versions.

    ///

    /// # Arguments

    /// * `node_id` - The text node to modify (DomNodeId containing both DOM and node IDs)

    /// * `text` - The new text content

    /// Change the image of a node (applied after callback returns)

    /// Re-render an image callback (for resize/animation updates)

    ///

    /// This triggers re-invocation of the RenderImageCallback associated with the node.

    /// Useful for:

    /// - Responding to window resize (image needs to match new size)

    /// - Animation frames (update OpenGL texture each frame)

    /// - Interactive content (user input changes rendering)

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

    ///

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

    /// Unlike returning `Update::RefreshDom`, this triggers only:

    /// - Re-invocation of all `RenderImageCallback` functions

    /// - GL texture swap in WebRender

    ///

    /// It does NOT trigger:

    /// - DOM rebuild (no `layout()` callback)

    /// - Display list resubmission (WebRender reuses existing scene)

    /// - Relayout

    ///

    /// Ideal for timer callbacks that animate OpenGL content at 60fps.

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

    ///

    /// This forces the VirtualView to call its layout callback with reason `DomRecreated`

    /// and submit a new display list to WebRender. The VirtualView's pipeline will be updated

    /// without affecting other parts of the window.

    ///

    /// Useful for:

    /// - Live preview panes (update when source code changes)

    /// - Dynamic content that needs manual refresh

    /// - Editor previews (re-parse and display new DOM)

    // Dom Tree Navigation

    /// Find a node by ID attribute in the layout tree

    ///

    /// Returns the NodeId of the first node with the given ID attribute, or None if not found.

        // Search through all nodes to find one with matching ID attribute

        }

    /// Get the parent node of the given node

    ///

    /// Returns None if the node has no parent (i.e., it's the root node)

    /// Get the next sibling of the given node

    ///

    /// Returns None if the node has no next sibling

    /// Get the previous sibling of the given node

    ///

    /// Returns None if the node has no previous sibling

    /// Get the first child of the given node

    ///

    /// Returns None if the node has no children

    /// Get the last child of the given node

    ///

    /// Returns None if the node has no children

    /// Get all direct children of the given node

    ///

    /// Returns an empty vector if the node has no children.

    /// Uses the contiguous node layout for efficient iteration.

        };

        };

        // Get first child - if none, return empty

        };

        // Collect children by walking the sibling chain

    /// Get the number of direct children of the given node

    ///

    /// Uses the contiguous node layout for efficient counting.

        };

        };

        // Get first child - if none, return 0

        };

        // Count children by walking the sibling chain

    /// Change the image mask of a node (applied after callback returns)

    /// Change CSS properties of a node (applied after callback returns)

    /// Set a single CSS property on a node (convenience method for widgets)

    ///

    /// This is a helper method that wraps `change_node_css_properties` for the common case

    /// of setting a single property. It uses the hit node's DOM ID automatically.

    ///

    /// # Arguments

    /// * `node_id` - The node to set the property on (uses hit node's DOM ID)

    /// * `property` - The CSS property to set

    /// Quickly override CSS properties on a node for animation or other

    /// transient visual changes. Writes go through

    /// `CssPropertyCache::user_overridden_properties`, which is consulted at

    /// higher priority than the static cascade, so this does not invalidate

    /// the styled DOM's CSS rules. Pass `CssProperty::Initial` for a given

    /// property type to remove any prior override for that type.

    /// Convenience wrapper for `override_node_css_properties` that targets a

    /// single property on the hit node's DOM (typical for animation callbacks).

    /// Scroll a node to a specific position (applied after callback returns)