azul_core/

events.rs

//! Event and callback filtering module

#[cfg(not(feature = "std"))]
use alloc::string::{String, ToString};
use alloc::{
    boxed::Box,
    collections::{btree_map::BTreeMap, btree_set::BTreeSet},
    vec::Vec,
};

use azul_css::AzString;

use crate::{
    callbacks::Update,
    dom::{DomId, DomNodeId, On},
    geom::{LogicalPosition, LogicalRect},
    hit_test::{FullHitTest, HitTestItem},
    id::NodeId,
    styled_dom::{ChangedCssProperty, NodeHierarchyItemId},
    task::Instant,
    OrderedMap,
};

/// Easing functions for smooth scroll animations
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EasingFunction {
    Linear,
    EaseInOut,
    EaseOut,
    /// Critically-damped spring settle (ledger #28, per the animation
    /// design doc): position eases like a spring released toward the
    /// target — fast initial pull, asymptote-free exact landing. Evaluated
    /// analytically from normalized time (same curve family the scroll
    /// physics integrates numerically).
    Spring,
}

pub type RestyleNodes = BTreeMap<NodeId, Vec<ChangedCssProperty>>;
pub type RelayoutNodes = BTreeMap<NodeId, Vec<ChangedCssProperty>>;
pub type RelayoutWords = BTreeMap<NodeId, AzString>;

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct FocusChange {
    pub old: Option<DomNodeId>,
    pub new: Option<DomNodeId>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CallbackToCall {
    pub node_id: NodeId,
    pub hit_test_item: Option<HitTestItem>,
    pub event_filter: EventFilter,
}

impl CallbackToCall {
    #[must_use]
    pub const fn new(
        node_id: NodeId,
        hit_test_item: Option<HitTestItem>,
        event_filter: EventFilter,
    ) -> Self {
        Self {
            node_id,
            hit_test_item,
            event_filter,
        }
    }

    /// Build a list of `CallbackToCall` entries for every node hit by the
    /// given hit test under the given DOM, tagged with `event_filter`.
    /// Returns an empty `Vec` when there is no hit test data for the DOM.
    #[must_use]
    pub fn from_hit_test(
        hit_test: &FullHitTest,
        dom_id: DomId,
        event_filter: EventFilter,
    ) -> Vec<Self> {
        let Some(hit) = hit_test.hovered_nodes.get(&dom_id) else {
            return Vec::new();
        };
        hit.regular_hit_test_nodes
            .iter()
            .map(|(node_id, item)| Self {
                node_id: *node_id,
                hit_test_item: Some(*item),
                event_filter,
            })
            .collect()
    }
}

#[derive(Debug, Copy, Clone, PartialEq, Eq)]
#[must_use = "ProcessEventResult must be used to determine if relayout/repaint is needed"]
pub enum ProcessEventResult {
    DoNothing = 0,
    ShouldReRenderCurrentWindow = 1,
    ShouldUpdateDisplayListCurrentWindow = 2,
    // GPU transforms changed: do another hit-test and recurse
    // until nothing has changed anymore
    UpdateHitTesterAndProcessAgain = 3,
    // Restyle or runtime edit changed layout-affecting properties:
    // re-run layout on the EXISTING StyledDom (no DOM rebuild).
    ShouldIncrementalRelayout = 4,
    // Full DOM rebuild via user's layout_callback()
    ShouldRegenerateDomCurrentWindow = 5,
    ShouldRegenerateDomAllWindows = 6,
}

impl ProcessEventResult {
    #[must_use]
    pub const fn order(&self) -> usize {
        use self::ProcessEventResult::{
            DoNothing, ShouldIncrementalRelayout, ShouldReRenderCurrentWindow,
            ShouldRegenerateDomAllWindows, ShouldRegenerateDomCurrentWindow,
            ShouldUpdateDisplayListCurrentWindow, UpdateHitTesterAndProcessAgain,
        };
        match self {
            DoNothing => 0,
            ShouldReRenderCurrentWindow => 1,
            ShouldUpdateDisplayListCurrentWindow => 2,
            UpdateHitTesterAndProcessAgain => 3,
            ShouldIncrementalRelayout => 4,
            ShouldRegenerateDomCurrentWindow => 5,
            ShouldRegenerateDomAllWindows => 6,
        }
    }
}

impl PartialOrd for ProcessEventResult {
    fn partial_cmp(&self, other: &Self) -> Option<core::cmp::Ordering> {
        self.order().partial_cmp(&other.order())
    }
}

impl Ord for ProcessEventResult {
    fn cmp(&self, other: &Self) -> core::cmp::Ordering {
        self.order().cmp(&other.order())
    }
}

impl ProcessEventResult {
    pub fn max_self(self, other: Self) -> Self {
        self.max(other)
    }
}

/// Tracks the origin of an event for proper handling.
///
/// This allows the system to distinguish between user input, programmatic
/// changes, and synthetic events generated by UI components.
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[repr(C)]
pub enum EventSource {
    /// Direct user input (mouse, keyboard, touch, gamepad)
    User,
    /// API call (programmatic scroll, focus change, etc.)
    Programmatic,
    /// Generated from UI interaction (scrollbar drag, synthetic events)
    Synthetic,
    /// Generated from lifecycle hooks (mount, unmount, resize)
    Lifecycle,
}

/// Event propagation phase (similar to DOM Level 2 Events).
///
/// Events can be intercepted at different phases:
/// - **Capture**: Event travels from root down to target (rarely used)
/// - **Target**: Event is at the target element
/// - **Bubble**: Event travels from target back up to root (most common)
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[repr(C)]
#[derive(Default)]
pub enum EventPhase {
    /// Event travels from root down to target
    Capture,
    /// Event is at the target element
    Target,
    /// Event bubbles from target back up to root
    #[default]
    Bubble,
}

/// Mouse button identifier for mouse events.
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[repr(C)]
pub enum MouseButton {
    Left,
    Middle,
    Right,
    Other(u8),
}

/// Scroll delta mode (how scroll deltas should be interpreted).
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[repr(C)]
pub enum ScrollDeltaMode {
    /// Delta is in pixels
    Pixel,
    /// Delta is in lines (e.g., 3 lines of text)
    Line,
    /// Delta is in pages
    Page,
}

/// Scroll direction for conditional event filtering.
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[repr(C)]
pub enum ScrollDirection {
    Up,
    Down,
    Left,
    Right,
}

// ============================================================================
// W3C CSSOM View Module - Scroll Into View Types
// ============================================================================

/// W3C-compliant scroll-into-view options
///
/// These options control how an element is scrolled into view, following
/// the CSSOM View Module specification.
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub struct ScrollIntoViewOptions {
    /// Vertical alignment: start, center, end, nearest (default: nearest)
    pub block: ScrollLogicalPosition,
    /// Horizontal alignment: start, center, end, nearest (default: nearest)
    /// Note: Named `inline_axis` to avoid conflict with C keyword `inline`
    pub inline_axis: ScrollLogicalPosition,
    /// Animation behavior: auto, instant, smooth (default: auto)
    pub behavior: ScrollIntoViewBehavior,
}

impl ScrollIntoViewOptions {
    /// Create options with "nearest" alignment for both axes
    #[must_use]
    pub const fn nearest() -> Self {
        Self {
            block: ScrollLogicalPosition::Nearest,
            inline_axis: ScrollLogicalPosition::Nearest,
            behavior: ScrollIntoViewBehavior::Auto,
        }
    }

    /// Create options with "center" alignment for both axes
    #[must_use]
    pub const fn center() -> Self {
        Self {
            block: ScrollLogicalPosition::Center,
            inline_axis: ScrollLogicalPosition::Center,
            behavior: ScrollIntoViewBehavior::Auto,
        }
    }

    /// Create options with "start" alignment for both axes
    #[must_use]
    pub const fn start() -> Self {
        Self {
            block: ScrollLogicalPosition::Start,
            inline_axis: ScrollLogicalPosition::Start,
            behavior: ScrollIntoViewBehavior::Auto,
        }
    }

    /// Create options to align the end of the target with the end of the viewport
    #[must_use]
    pub const fn end() -> Self {
        Self {
            block: ScrollLogicalPosition::End,
            inline_axis: ScrollLogicalPosition::End,
            behavior: ScrollIntoViewBehavior::Auto,
        }
    }

    /// Set instant scroll behavior
    #[must_use]
    pub const fn with_instant(mut self) -> Self {
        self.behavior = ScrollIntoViewBehavior::Instant;
        self
    }

    /// Set smooth scroll behavior
    #[must_use]
    pub const fn with_smooth(mut self) -> Self {
        self.behavior = ScrollIntoViewBehavior::Smooth;
        self
    }
}

/// Scroll alignment for vertical (block) or horizontal (inline) axis
///
/// Determines where the target element should be positioned within
/// the scroll container's visible area.
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Default)]
pub enum ScrollLogicalPosition {
    /// Align target's start edge with container's start edge
    Start,
    /// Center target within container
    Center,
    /// Align target's end edge with container's end edge
    End,
    /// Minimum scroll distance to make target fully visible (default)
    #[default]
    Nearest,
}

/// Scroll animation behavior for scrollIntoView API
///
/// This is distinct from the CSS `scroll-behavior` property, as it also
/// supports the `Instant` option which CSS does not have.
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Default)]
pub enum ScrollIntoViewBehavior {
    /// Respect CSS scroll-behavior property (default)
    #[default]
    Auto,
    /// Immediate jump without animation
    Instant,
    /// Animated smooth scroll
    Smooth,
}

/// Reason why a lifecycle event was triggered.
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[repr(C)]
pub enum LifecycleReason {
    /// First appearance in DOM
    InitialMount,
    /// Removed and re-added to DOM
    Remount,
    /// Layout bounds changed
    Resize,
    /// Props or state changed
    Update,
    /// Node was removed from DOM
    Unmount,
    /// A `<transient-window>` was closed by the USER (outside click, Escape),
    /// not by the app flipping `open`.
    Dismiss,
    /// A `<transient-window>` was torn off its anchor into a free toplevel
    /// by the user's drag. `current_bounds` is where it went, in the parent.
    TearOff,
    /// A torn-off `<transient-window>` was docked back (onto its anchor or a
    /// drop zone) by the user's drag.
    Dock,
}

/// Keyboard modifier keys state.
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, Default)]
#[repr(C)]
pub struct KeyModifiers {
    pub shift: bool,
    pub ctrl: bool,
    pub alt: bool,
    pub meta: bool,
}

impl KeyModifiers {
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    #[must_use]
    pub const fn with_shift(mut self) -> Self {
        self.shift = true;
        self
    }

    #[must_use]
    pub const fn with_ctrl(mut self) -> Self {
        self.ctrl = true;
        self
    }

    #[must_use]
    pub const fn with_alt(mut self) -> Self {
        self.alt = true;
        self
    }

    #[must_use]
    pub const fn with_meta(mut self) -> Self {
        self.meta = true;
        self
    }

    #[must_use]
    pub const fn is_empty(&self) -> bool {
        !self.shift && !self.ctrl && !self.alt && !self.meta
    }
}

/// What kind of device produced a pointer event.
///
/// The same discriminator the web calls `PointerEvent.pointerType`, GTK calls
/// `GdkInputSource` and Qt calls `QInputDevice::DeviceType`. Azul splits Mouse,
/// Touch and Pen into separate FILTERS, which is a stronger guarantee than a
/// runtime tag — but it cannot express the distinctions WITHIN the pointer
/// family, and those matter:
///
/// - A touchpad and a mouse both arrive as a synthesized pointer. Telling them
///   apart is what lets an app know a pinch gesture is possible at all, and
///   whether "scroll" means a wheel detent or a continuous drag.
/// - A trackball and a trackpoint have their own acceleration and scroll
///   semantics, which is why GTK and Android name them separately.
/// - A pen reported through the pointer path (a stylus acting as a mouse, the
///   Wayland tablet bridge) is not a finger and not a mouse.
#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[repr(C)]
pub enum PointerSource {
    /// The platform did not say.
    Unknown,
    /// A mouse.
    Mouse,
    /// An indirect touch surface — a laptop trackpad or a Magic Trackpad.
    Touchpad,
    /// A trackball.
    Trackball,
    /// A pointing stick (ThinkPad nub).
    Trackpoint,
    /// A direct touch surface reporting through the pointer path.
    Touchscreen,
    /// A stylus tip.
    Pen,
    /// The inverted end of a stylus.
    Eraser,
}

/// Type-specific event data for mouse events.
#[derive(Debug, Clone, Copy, PartialEq)]
#[repr(C)]
pub struct MouseEventData {
    /// Position of the mouse cursor
    pub position: LogicalPosition,
    /// Which button was pressed/released
    pub button: MouseButton,
    /// Bitmask of currently pressed buttons
    pub buttons: u8,
    /// Modifier keys state
    pub modifiers: KeyModifiers,
    /// What produced this event. APPENDED for ABI stability.
    pub source: PointerSource,
    /// Which physical device produced it, or `0` when the platform does not
    /// say. APPENDED for ABI stability.
    ///
    /// Only `PenState`, `GamepadState` and `TabletPadState` carried a device id
    /// before, so a mouse event could not say WHICH of two mice moved — and
    /// `MouseState` used to be a single global, which is why multi-seat (a
    /// kiosk, a shared display, two people on one compositor) was not
    /// expressible at all. The state fans out per seat since 9b-ii; this
    /// field stays the PHYSICAL device, `seat_id` below says which cursor.
    pub device_id: u64,
    /// Which pointer SEAT - which independent cursor - produced it. APPENDED
    /// (9b-ii). `PRIMARY_POINTER_SEAT` (0) for the ordinary mouse, which is
    /// every event on a platform with one cursor; an X11 MPX master id or a
    /// Wayland seat otherwise. A callback that receives a non-zero value
    /// reads that seat's state through `get_pointer_seat_state`, because
    /// `get_current_mouse_state` is the PRIMARY seat by definition.
    pub seat_id: u64,
}

impl Default for MouseEventData {
    fn default() -> Self {
        Self {
            position: LogicalPosition { x: 0.0, y: 0.0 },
            button: MouseButton::Left,
            buttons: 0,
            modifiers: KeyModifiers::default(),
            source: PointerSource::Unknown,
            device_id: 0,
            seat_id: crate::window::PRIMARY_POINTER_SEAT,
        }
    }
}

/// Type-specific event data for keyboard events.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct KeyboardEventData {
    /// The virtual key code
    pub key_code: u32,
    /// The character produced (if any)
    pub char_code: Option<char>,
    /// Modifier keys state
    pub modifiers: KeyModifiers,
    /// Whether this is a repeat event
    pub repeat: bool,
    /// Which physical keyboard produced this event, or `0` when the platform
    /// does not say. APPENDED for ABI stability.
    ///
    /// Same reasoning as `MouseEventData::device_id`: with two keyboards
    /// attached — a laptop's built-in and an external, or a barcode scanner
    /// presenting as a keyboard — nothing could tell their input apart.
    pub device_id: u64,
    /// Which KEYBOARD SEAT pressed (9b-ii-a-i): `PRIMARY_POINTER_SEAT` for
    /// the ordinary keyboard, a seat id for a second person's - the same
    /// number their pointer events carry.
    pub seat_id: u64,
}

impl Default for KeyboardEventData {
    fn default() -> Self {
        Self {
            key_code: 0,
            char_code: None,
            modifiers: KeyModifiers::default(),
            repeat: false,
            device_id: 0,
            seat_id: crate::window::PRIMARY_POINTER_SEAT,
        }
    }
}

/// Type-specific event data for scroll events.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ScrollEventData {
    /// Scroll delta (dx, dy)
    pub delta: LogicalPosition,
    /// How the delta should be interpreted
    pub delta_mode: ScrollDeltaMode,
    /// Which pointer SEAT turned the wheel (9b-ii-b); `PRIMARY_POINTER_SEAT`
    /// for the ordinary mouse. A second cursor's wheel scrolls the node under
    /// THAT cursor, so the event names the seat the way a mouse event does.
    pub seat_id: u64,
}

/// Type-specific event data for touch events.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct TouchEventData {
    /// Touch identifier
    pub id: u64,
    /// Touch position
    pub position: LogicalPosition,
    /// Touch force/pressure (0.0 - 1.0)
    pub force: f32,
    /// The SEAT whose touchscreen this is (9b-ii-a-i-c); ids are per seat.
    pub seat_id: u64,
}

/// Type-specific event data for clipboard events.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ClipboardEventData {
    /// The clipboard content (for paste events)
    pub content: Option<String>,
}

/// Type-specific event data for lifecycle events.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct LifecycleEventData {
    /// Why this lifecycle event was triggered
    pub reason: LifecycleReason,
    /// Previous layout bounds (for resize events)
    pub previous_bounds: Option<LogicalRect>,
    /// Current layout bounds
    pub current_bounds: LogicalRect,
}

/// Type-specific event data for window events.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct WindowEventData {
    /// Window size (for resize events)
    pub size: Option<LogicalRect>,
    /// Window position (for move events)
    pub position: Option<LogicalPosition>,
}

/// Type-specific event data for text-input (editing) events.
///
/// Data carried by `EventType::RawMouseMotion`.
///
/// Raw motion is what a 3D viewport, a map orbit, an infinite-drag number
/// scrubber and a first-person camera all need, and it is NOT the difference
/// between two cursor positions. Absolute positions have already had the OS
/// pointer-acceleration curve applied and are clamped to the screen, so
/// differencing them gives accelerated motion that stops dead at the edge of
/// the display. These deltas are pre-acceleration and unbounded.
/// Where the caret sits INSIDE an open IME preedit.
///
/// Both offsets are into the preedit string, not into the document: the
/// preedit is not committed text and has no position in the document until it
/// is. An IME uses this to place its candidate window under the segment being
/// edited, and a `begin != end` pair is a SELECTED segment - several IMEs
/// (Japanese conversion especially) move a highlighted region through the
/// preedit as the user cycles candidates.
///
/// A named struct rather than the `(usize, usize)` this used to be, because a
/// non-empty tuple has no C representation - so the accessor could not be
/// exposed at all and no binding could read an IME's caret.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
#[repr(C)]
pub struct CompositionCursor {
    /// Start offset in the preedit, in bytes.
    pub begin: usize,
    /// End offset. Equal to `begin` for a caret with no selected segment.
    pub end: usize,
}

azul_css::impl_option!(
    CompositionCursor,
    OptionCompositionCursor,
    [Debug, Copy, Clone, PartialEq, Eq]
);

/// `#[repr(C)]` because `CallbackInfo::get_raw_mouse_motion` hands this
/// across the C API. Without it the layout is undefined at the boundary and
/// the generated bindings read garbage fields.
#[derive(Debug, Clone, Copy, PartialEq)]
#[repr(C)]
pub struct RawMotionEventData {
    /// Horizontal motion in the device's own units. NOT logical pixels: a
    /// mouse reports counts, whose size depends on its DPI, which is exactly
    /// why a sensitivity setting exists.
    pub dx: f64,
    /// Vertical motion, same units.
    pub dy: f64,
    /// Which device moved, or `0` when the platform does not say.
    pub device_id: u64,
}

azul_css::impl_option!(
    RawMotionEventData,
    OptionRawMotionEventData,
    [Debug, Copy, Clone, PartialEq]
);

/// Data carried by a `MediaControl` event (9h-i-a-i-a, 9h-i-a-i-b): what the
/// platform's media controls asked for. The URI of an `OpenUri` is not
/// repeated here - `CallbackInfo::get_media_control_request` carries the
/// whole request.
#[derive(Debug, Clone, Copy, PartialEq)]
#[repr(C)]
pub struct MediaControlEventData {
    /// Microseconds; relative for `SeekRelative`, absolute for `SeekAbsolute`.
    pub position_us: i64,
    pub kind: crate::media_session::MediaControlKind,
    /// The requested volume for `SetVolume` (`0.0` silent, `1.0` full), `0.0`
    /// for every other kind.
    pub volume: f32,
}

/// Data carried by a `SystemAudioChange` event (9h-i-a-i-d-i): what the
/// system did with the audio the app took over. Also readable through
/// `CallbackInfo::get_system_audio_change`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(C)]
pub struct SystemAudioEventData {
    pub change: crate::media_session::SystemAudioChange,
}

/// Data carried by the three IME composition events.
///
/// Every desktop shell already runs a real IME client — Win32 `WM_IME_*` with
/// candidate-window positioning, macOS `NSTextInputClient`, Wayland
/// `zwp_text_input_v3` preedit/commit, X11 XIM plus the xkb Compose layer —
/// and all of it terminated in the engine's text cache. The built-in text
/// widgets therefore worked, but an app rendering its own composition (a code
/// editor, a terminal, a chat box with inline candidates) had no way to see
/// it, because the `Composition*` filters had no event to carry.
///
/// The shape is the intersection of what the platforms report, which is also
/// what W3C `CompositionEvent` and Wayland `preedit_string` agree on.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CompositionEventData {
    /// The preedit (composition) text as it currently stands. Empty on
    /// `CompositionStart`, and on `CompositionEnd` this is the committed
    /// string — W3C defines `compositionend.data` as what was committed, not
    /// what was pending.
    pub data: String,
    /// Byte offset of the selection/caret start within `data`. Wayland sends
    /// this directly (`preedit_string(text, cursor_begin, cursor_end)`);
    /// Win32 derives it from `GCS_CURSORPOS`; macOS from the `selectedRange`
    /// passed to `setMarkedText:selectedRange:replacementRange:`.
    pub cursor_begin: usize,
    /// Byte offset of the selection/caret end within `data`. Equal to
    /// `cursor_begin` for a collapsed caret.
    pub cursor_end: usize,
    /// The SEAT whose input method this is (9b-ii-a-i-d-ii-c-i); the primary
    /// is `PRIMARY_POINTER_SEAT`. The Focus filter delivers a seat's
    /// composition to that seat's focused node.
    pub seat_id: u64,
}

/// Carried by `EventType::Input` events so that text-input callbacks can read
/// the edit details directly off the event — matching how mouse/keyboard/scroll
/// callbacks read their data — instead of having to reach into the
/// `TextInputManager`'s pending changeset. The edited node is already available
/// via `SyntheticEvent.target`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TextInputEventData {
    /// The text inserted by this edit (empty for pure deletions).
    pub inserted_text: String,
    /// The text content of the node *before* this edit was applied.
    pub old_text: String,
}

/// Identifies WHICH pending structural changeset a notification is for.
///
/// Carried by `EventType::DocumentEdit` events; the app acks with the same
/// id via `mark_document_edit_applied`. The full changeset is intentionally
/// NOT copied onto the event — it stays single-instance in the window
/// (one-pending-changeset model).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct DocumentEditEventData {
    /// The commit-handshake id of the recorded changeset.
    pub changeset_id: u64,
}

/// Union of all possible event data types.
#[derive(Debug, Clone, PartialEq)]
pub enum EventData {
    /// Mouse event data
    Mouse(MouseEventData),
    /// Keyboard event data
    Keyboard(KeyboardEventData),
    /// Scroll event data
    Scroll(ScrollEventData),
    /// Touch event data
    Touch(TouchEventData),
    /// Clipboard event data
    Clipboard(ClipboardEventData),
    /// Text-input (editing) event data
    TextInput(TextInputEventData),
    /// Structural document-edit notification data
    DocumentEdit(DocumentEditEventData),
    /// Lifecycle event data
    Lifecycle(LifecycleEventData),
    /// Window event data
    Window(WindowEventData),
    /// No additional data
    None,
    /// IME composition data. APPENDED at the end for ABI stability — this is
    /// `#[repr(C, u8)]`-adjacent, so a variant inserted in the middle would
    /// renumber every discriminant after it.
    Composition(CompositionEventData),
    /// Raw, pre-acceleration pointer motion. APPENDED at the end.
    RawMotion(RawMotionEventData),
    /// A media seek (9h-i-a-i-a). APPENDED for ABI stability.
    MediaControl(MediaControlEventData),
    SystemAudio(SystemAudioEventData),
}

/// High-level event type classification.
///
/// This enum categorizes all possible events that can occur in the UI.
/// It extends the existing event system with new event types for
/// lifecycle, clipboard, media, and form handling.
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[repr(C)]
pub enum EventType {
    // Mouse Events
    /// Mouse cursor is over the element
    MouseOver,
    /// Mouse cursor entered the element
    MouseEnter,
    /// Mouse cursor left the element
    MouseLeave,
    /// Mouse left the element OR moved to a child element (W3C `mouseout`, bubbles)
    MouseOut,
    /// Mouse button pressed
    MouseDown,
    /// Mouse button released
    MouseUp,
    /// Mouse click (down + up on same element)
    Click,
    /// Mouse double-click
    DoubleClick,
    /// Right-click / context menu
    ContextMenu,

    // Keyboard Events
    /// Key pressed down
    KeyDown,
    /// Key released
    KeyUp,
    /// Character input (respects locale/keyboard layout)
    KeyPress,

    // IME Composition Events
    /// IME composition started
    CompositionStart,
    /// IME composition updated (intermediate text changed)
    CompositionUpdate,
    /// IME composition ended (final text committed)
    CompositionEnd,

    // Focus Events
    /// Element received focus
    Focus,
    /// Element lost focus
    Blur,
    /// Focus entered element or its children
    FocusIn,
    /// Focus left element and its children
    FocusOut,

    // Input Events
    /// Input value is being changed (fires on every keystroke)
    Input,
    /// Input value has changed (fires after editing complete)
    Change,
    /// Form submitted
    Submit,
    /// Form reset
    Reset,
    /// Form validation failed
    Invalid,

    // Scroll Events
    /// Element is being scrolled
    Scroll,
    /// Scroll started
    ScrollStart,
    /// Scroll ended
    ScrollEnd,

    // Drag Events
    /// Drag operation started
    DragStart,
    /// Element is being dragged
    Drag,
    /// Drag operation ended
    DragEnd,
    /// Dragged element entered drop target
    DragEnter,
    /// Dragged element is over drop target
    DragOver,
    /// Dragged element left drop target
    DragLeave,
    /// Element was dropped
    Drop,

    // Touch Events
    /// Touch started
    TouchStart,
    /// Touch moved
    TouchMove,
    /// Touch ended
    TouchEnd,
    /// Touch cancelled
    TouchCancel,

    // Pen / Stylus Events (W3C PointerEvent, pointerType "pen")
    /// Pen tip made contact (or pen entered while down)
    PenDown,
    /// Pen moved (in contact or hovering in range)
    PenMove,
    /// Pen tip lifted
    PenUp,
    /// Pen entered hover/sensing range (proximity in)
    PenEnter,
    /// Pen left hover/sensing range (proximity out)
    PenLeave,

    // Gesture Events
    /// Long press detected (touch or mouse held down)
    LongPress,
    /// Swipe gesture to the left
    SwipeLeft,
    /// Swipe gesture to the right
    SwipeRight,
    /// Swipe gesture upward
    SwipeUp,
    /// Swipe gesture downward
    SwipeDown,
    /// Pinch-in gesture (zoom out)
    PinchIn,
    /// Pinch-out gesture (zoom in)
    PinchOut,
    /// Clockwise rotation gesture
    RotateClockwise,
    /// Counter-clockwise rotation gesture
    RotateCounterClockwise,

    // Clipboard Events
    /// Content copied to clipboard
    Copy,
    /// Content cut to clipboard
    Cut,
    /// Content pasted from clipboard
    Paste,

    // Media Events
    /// Media playback started
    Play,
    /// Media playback paused
    Pause,
    /// Media playback ended
    Ended,
    /// Media time updated
    TimeUpdate,
    /// Media volume changed
    VolumeChange,
    /// Media error occurred
    MediaError,

    // Lifecycle Events
    /// Component was mounted to the DOM
    Mount,
    /// Component will be unmounted from the DOM
    Unmount,
    /// Component was updated
    Update,
    /// Component layout bounds changed
    Resize,
    /// A `<transient-window>` was dismissed by the user (outside click or
    /// Escape). Fired on the transient node so the app can drop its `open`
    /// flag; the surface is already gone by the time this runs.
    Dismiss,
    /// A `<transient-window>` was torn off by the user's drag and is now a
    /// free toplevel. Fired on the transient node; the lifecycle data's
    /// `current_bounds` is the toplevel's rect in the parent's coordinates,
    /// for apps that persist their palette layout.
    TearOff,
    /// A torn-off `<transient-window>` was docked back by the user's drag.
    Dock,

    // Window Events
    /// Window resized
    WindowResize,
    /// Window moved
    WindowMove,
    /// Window close requested
    WindowClose,
    /// The window's frame state changed — minimized, maximized, restored to
    /// normal, or entered/left fullscreen.
    ///
    /// Read the new state from `flags.frame` on the current window state; the
    /// event carries no payload of its own because the flag IS the payload and
    /// a callback that cares will already be reading window state.
    WindowFrameChanged,
    /// Window received focus
    WindowFocusIn,
    /// Window lost focus
    WindowFocusOut,
    /// System theme changed
    ThemeChange,
    /// Window DPI/scale factor changed (moved to different monitor)
    WindowDpiChanged,
    /// Window moved to a different monitor
    WindowMonitorChanged,

    // Application Events
    /// A monitor/display was connected
    MonitorConnected,
    /// A monitor/display was disconnected
    MonitorDisconnected,

    // File Events
    /// File is being hovered
    FileHover,
    /// File was dropped
    FileDrop,
    /// File hover cancelled
    FileHoverCancel,

    // Hardware input-device Events (P6 sensors / gamepad)
    /// A motion-sensor reading (accelerometer / gyroscope / magnetometer)
    /// changed. Read the value with `CallbackInfo::get_sensor_reading`.
    SensorChanged,
    /// A gamepad's buttons / axes changed, or one was (dis)connected. Read it
    /// with `CallbackInfo::get_primary_gamepad` / `get_gamepad_state`.
    GamepadInput,

    // Geolocation Events (MWA-A1 — synthesized by the capability pump's
    // GeolocationManager EventProvider; both filter enums already carried
    // the matching variants, only this dispatch type was missing them).
    /// A new GPS / network location fix arrived. Read it with
    /// `CallbackInfo::get_geolocation_fix`.
    GeolocationFix,
    /// The native geolocation subscription errored, timed out, or was
    /// revoked.
    GeolocationError,

    // Async capability outcomes (MWA-A1b — synthesized by the capability
    // pump's manager EventProviders so idle apps observe prompt results).
    /// A permission's OS-observed state changed (granted / denied /
    /// revoked / restricted). Targeted at the capability's most recent
    /// subscriber node when known, else the root. Read the new state via
    /// `CallbackInfo` permission accessors.
    PermissionChanged,
    /// A biometric authentication prompt completed. Read the outcome via
    /// `CallbackInfo::get_biometric_result`.
    BiometricResult,
    /// The screen eyedropper started by `CallbackInfo::pick_screen_color`
    /// finished - the user picked a pixel, or cancelled. Window-level (the
    /// pick is not bound to a node); read the colour via
    /// `CallbackInfo::get_picked_screen_color` (`None` = cancelled).
    ScreenColorPicked,
    /// A keyring store / get / delete operation completed. Read the outcome
    /// via `CallbackInfo::get_keyring_result`.
    KeyringResult,

    // Structural document editing (C11 — synthesized once per recorded
    // changeset by the LayoutWindow's document-edit EventProvider).
    /// A STRUCTURAL document edit (Enter split / Backspace merge / wrap /
    /// selection-spanning replace…) was recorded and awaits the app's
    /// apply-and-ack. Fired ONCE per changeset so the app's apply loop is
    /// prompt instead of polling `get_pending_document_edit()` on its next
    /// unrelated callback. The changeset id rides on
    /// `EventData::DocumentEdit`; the full changeset is read via
    /// `CallbackInfo` / `LayoutWindow::get_pending_document_edit()`.
    DocumentEdit,

    /// The text of an editable node CHANGED - fired once per commit, AFTER
    /// the edit is applied (typing, IME commit, deletion, paste, undo/redo:
    /// everything that writes the text overlay).
    ///
    /// `Input` is the `beforeinput` of this pair: it fires BEFORE the
    /// pending insertion is applied so a listener can `prevent_default`,
    /// which means a model that reads `get_unsynced_text_edits` from an
    /// `Input` callback is always one keystroke behind. A listener that
    /// wants the committed text - a word counter, a dirty flag, a live
    /// preview - listens here instead; the edits are already in the sync
    /// channel when this runs. Deletions used to be the only edits notified
    /// post-commit (through a second `Input`); this is the uniform spelling.
    TextChanged,
    /// An input device was attached. APPENDED at the end for ABI stability.
    ///
    /// `ApplicationEventFilter` has carried `DeviceConnected` since it was
    /// introduced, with no `EventType` able to reach it. Hotplug is observable
    /// on every backend — gilrs already reports gamepad arrive/leave through
    /// the capability pump, Wayland has `wl_seat.capabilities` and the
    /// `zwp_tablet_seat_v2` add/remove events, X11 has `XI_HierarchyChanged`,
    /// Win32 has `WM_DEVICECHANGE` — so the filter was the only thing missing.
    DeviceConnected,
    /// An input device was detached. See [`EventType::DeviceConnected`].
    DeviceDisconnected,
    /// The pen barrel was squeezed. APPENDED at the end for ABI stability.
    ///
    /// Apple Pencil Pro's squeeze, surfaced by `UIPencilInteraction`. The
    /// Hover and Window filter variants have existed with no `EventType` able
    /// to reach them.
    PenSqueeze,
    /// The pen was double-tapped on its barrel — Apple Pencil 2 and later,
    /// also `UIPencilInteraction`. See [`EventType::PenSqueeze`].
    PenDoubleTap,
    /// The pen is in range but not touching. Wayland reports it as
    /// `proximity_in` plus `distance`, Win32 as `POINTER_FLAG_INRANGE` without
    /// `POINTER_FLAG_INCONTACT`, Android as `ACTION_HOVER_MOVE` with a stylus
    /// tool type, macOS as an `NSEventSubtype::TabletProximity` subtype on the
    /// ordinary mouse-event path. See [`EventType::PenSqueeze`].
    PenHover,
    /// A component's default action was invoked — Enter/Space on a focused
    /// control, or the accessibility `Default` action. Distinct from `Click`:
    /// that is the pointer spelling, this is the component-level one that
    /// `ComponentEventFilter::DefaultAction` subscribes to.
    DefaultAction,
    /// A component's selection changed. `ComponentEventFilter::Selected` has
    /// existed with no `EventType` and no match arm.
    Selected,
    /// A HID device delivered an input report. APPENDED at the end.
    ///
    /// The escape hatch for devices azul does not model — flight sticks,
    /// wheels, 6-DOF mice, pedals, Stream Decks. Read the bytes via
    /// `CallbackInfo::get_hid_reports`.
    HidReport,
    /// A modifier or lock key changed state. APPENDED at the end.
    ///
    /// Modifiers arrive today only as ordinary key events, so an app tracking
    /// "is Shift down" has to watch every KeyDown and KeyUp and reconstruct
    /// it — and gets it wrong across a focus loss, because the KeyUp for a
    /// modifier released while another window had focus never arrives. This
    /// event carries the resolved state instead.
    ModifiersChanged,
    /// Raw pointer motion, pre-acceleration and unclamped. APPENDED at the
    /// end for ABI stability.
    ///
    /// `MouseState.is_cursor_locked` has existed since the beginning,
    /// documented as "important for applications like games", with no event
    /// carrying a delta behind it — so pointer lock was a flag that did
    /// nothing. This is the event it was waiting for.
    RawMouseMotion,
    /// A dial or rotary encoder turned. APPENDED at the end for ABI stability.
    ///
    /// The Surface Dial, a tablet pad's dial, a Wear crown, an Apple Digital
    /// Crown. `DialState` (rotation, detents, pressed, contact point) has been
    /// readable through `CallbackInfo::get_dial_state()` since the type
    /// landed, with no event to subscribe to — so a dial could only be POLLED
    /// from an unrelated callback that happened to run.
    DialRotate,
    /// A dial with a physical click was pressed. APPENDED at the end.
    DialClick,
    /// The pointer MOVED while over this node. APPENDED at the end.
    ///
    /// W3C `mousemove`. This is the event `MouseOver` used to be: until
    /// now azul had no movement event at all, and `MouseOver` was emitted
    /// on every cursor move - `mousemove` semantics under the `mouseover`
    /// name. `MouseOver` now means what the spec says (the pointer
    /// ENTERED the node) and movement lives here.
    MouseMove,
    /// The platform's media controls asked for a SEEK (9h-i-a-i-a): a desktop
    /// scrubber, a lock-screen slider, `playerctl position`. APPENDED at the
    /// end for ABI stability. Unlike Play/Pause/Next, which arrive as media
    /// KEY events, a seek carries a position - read it with
    /// `CallbackInfo::get_media_control_request`.
    MediaControl,
    /// The pointer lock changed hands (9d-ii-c): the app took or released it,
    /// or the platform ended it - every grab-based backend drops the grab
    /// when the window loses focus, and a Wayland compositor may end a
    /// constraint at any time. Both directions, like the browser's
    /// `pointerlockchange`; read `mouse_state.is_cursor_locked` for which.
    /// Nothing re-takes a lost lock on focus return (USER RULING
    /// 2026-09-03): an app that wants it back asks again from
    /// `WindowFocusReceived`.
    PointerLockChange,
    /// The system did something with the audio the app took over
    /// (9h-i-a-i-d-i): an interruption began or ended, focus was ducked,
    /// granted, or lost. Application-level, at the root; the payload is
    /// `EventData::SystemAudio` and `CallbackInfo::get_system_audio_change`.
    SystemAudioChange,
}

/// Unified event wrapper (similar to React's `SyntheticEvent`).
///
/// All events in the system are wrapped in this structure, providing
/// a consistent interface and enabling event propagation control.
#[derive(Debug, Clone, PartialEq)]
#[allow(clippy::struct_excessive_bools)] // four independent propagation flags — W3C's own model
pub struct SyntheticEvent {
    /// The type of event
    pub event_type: EventType,

    /// Where the event came from
    pub source: EventSource,

    /// Current propagation phase
    pub phase: EventPhase,

    /// Target node that the event was dispatched to
    pub target: DomNodeId,

    /// Current node in the propagation path
    pub current_target: DomNodeId,

    /// Timestamp when event was created
    pub timestamp: Instant,

    /// Type-specific event data
    pub data: EventData,

    /// Whether propagation has been stopped
    pub stopped: bool,

    /// Whether immediate propagation has been stopped
    pub stopped_immediate: bool,

    /// Whether default action has been prevented
    pub prevented_default: bool,

    /// Deliver at the target ONLY — no capture, no bubble.
    ///
    /// Set on the release synthesised for the node that was PRESSED when the
    /// pointer releases somewhere else (press-target capture, see
    /// `HoverManager::apply_press_target_capture`): that node owes a
    /// `MouseUp`, but its ancestors already see the real release through the
    /// hovered node's propagation path and must not see it twice.
    pub at_target_only: bool,
}

impl SyntheticEvent {
    /// Create a new synthetic event.
    ///
    /// # Parameters
    /// - `timestamp`: Current time from `(system_callbacks.get_system_time_fn.cb)()`
    #[must_use]
    pub const fn new(
        event_type: EventType,
        source: EventSource,
        target: DomNodeId,
        timestamp: Instant,
        data: EventData,
    ) -> Self {
        Self {
            event_type,
            source,
            phase: EventPhase::Target,
            target,
            current_target: target,
            timestamp,
            data,
            stopped: false,
            stopped_immediate: false,
            prevented_default: false,
            at_target_only: false,
        }
    }

    /// This event, delivered at its target only (see [`Self::at_target_only`]).
    #[must_use]
    pub const fn at_target_only(mut self) -> Self {
        self.at_target_only = true;
        self
    }

    /// Stop event propagation after the current phase completes.
    ///
    /// This prevents the event from reaching handlers in subsequent phases
    /// (e.g., stopping during capture prevents bubble phase).
    pub const fn stop_propagation(&mut self) {
        self.stopped = true;
    }

    /// Stop event propagation immediately.
    ///
    /// This prevents any further handlers from being called, even on the
    /// current target element.
    pub const fn stop_immediate_propagation(&mut self) {
        self.stopped_immediate = true;
        self.stopped = true;
    }

    /// Prevent the default action associated with this event.
    ///
    /// For example, prevents form submission on Enter key, or prevents
    /// text selection on drag.
    pub const fn prevent_default(&mut self) {
        self.prevented_default = true;
    }

    /// Check if propagation was stopped.
    #[must_use]
    pub const fn is_propagation_stopped(&self) -> bool {
        self.stopped
    }

    /// Check if immediate propagation was stopped.
    #[must_use]
    pub const fn is_immediate_propagation_stopped(&self) -> bool {
        self.stopped_immediate
    }

    /// Check if default action was prevented.
    #[must_use]
    pub const fn is_default_prevented(&self) -> bool {
        self.prevented_default
    }
}

/// Result of event propagation through DOM tree.
#[derive(Debug, Clone, Default)]
pub struct PropagationResult {
    /// Callbacks that should be invoked, in order
    pub callbacks_to_invoke: Vec<(NodeId, EventFilter)>,
    /// Whether default action should be prevented
    pub default_prevented: bool,
}

/// Get the path from root to target node in the DOM tree.
///
/// This is used for event propagation - we need to know which nodes
/// are ancestors of the target to implement capture/bubble phases.
///
/// Returns nodes in order from root to target (inclusive).
#[must_use]
pub fn get_dom_path(
    node_hierarchy: &crate::id::NodeHierarchy,
    target_node: NodeHierarchyItemId,
) -> Vec<NodeId> {
    let mut path = Vec::new();
    let Some(target_node_id) = target_node.into_crate_internal() else {
        return path;
    };

    let hier_ref = node_hierarchy.as_ref();

    // Build path from target to root. Bounded by the node count and guarded by a
    // visited-set: a corrupt hierarchy with a parent cycle (or a parent chain
    // longer than the arena) would otherwise loop forever / OOM here, and this
    // runs on every event dispatch.
    let node_count = hier_ref.len();
    let mut visited: BTreeSet<NodeId> = BTreeSet::new();
    let mut current = Some(target_node_id);
    while let Some(node_id) = current {
        if path.len() > node_count || !visited.insert(node_id) {
            // Cycle or overrun detected: stop rather than spin forever.
            break;
        }
        path.push(node_id);
        current = hier_ref.get(node_id).and_then(|node| node.parent);
    }

    // Reverse to get root → target order
    path.reverse();
    path
}

/// Propagate event through DOM tree with capture and bubble phases.
///
/// This implements DOM Level 2 event propagation:
/// 1. **Capture Phase**: Event travels from root down to target
/// 2. **Target Phase**: Event is at the target element
/// 3. **Bubble Phase**: Event travels from target back up to root
///
/// The event can be stopped at any point via `stopPropagation()` or
/// `stopImmediatePropagation()`.
///
/// # Panics
///
/// Panics if `path` is empty; it must contain at least the target node.
pub fn propagate_event(
    event: &mut SyntheticEvent,
    node_hierarchy: &crate::id::NodeHierarchy,
    callbacks: &BTreeMap<NodeId, Vec<EventFilter>>,
) -> PropagationResult {
    let path = get_dom_path(node_hierarchy, event.target.node);
    if path.is_empty() {
        return PropagationResult::default();
    }

    let ancestors = &path[..path.len().saturating_sub(1)];
    let target_node_id = *path.last().unwrap();

    let mut result = PropagationResult::default();

    // A captured release (see `SyntheticEvent::at_target_only`) reaches its
    // target and nothing else: the ancestors get the real release through
    // the hovered node's path.
    if event.at_target_only {
        propagate_target_phase(event, target_node_id, callbacks, &mut result);
        result.default_prevented = event.prevented_default;
        return result;
    }

    // Phase 1: Capture (root → target)
    propagate_phase(
        event,
        ancestors.iter().copied(),
        EventPhase::Capture,
        callbacks,
        &mut result,
    );

    // Phase 2: Target
    if !event.stopped {
        propagate_target_phase(event, target_node_id, callbacks, &mut result);
    }

    // Phase 3: Bubble (target → root) — unless the event type does not bubble.
    if !event.stopped && event.event_type.bubbles() {
        propagate_phase(
            event,
            ancestors.iter().rev().copied(),
            EventPhase::Bubble,
            callbacks,
            &mut result,
        );
    }

    result.default_prevented = event.prevented_default;
    result
}

impl EventType {
    /// Whether the event reaches the target's ANCESTORS in the bubble phase.
    ///
    /// Enter/leave events do not bubble (`W3C` `mouseenter`/`mouseleave`,
    /// `pointerenter`/`pointerleave`): each node that gained or lost hover
    /// gets its OWN event (`event_determination` generates them per node), so
    /// bubbling a child's leave to its parent tells the parent the pointer
    /// left IT while it is still inside — which is how a slider's drag ended
    /// the moment the pointer slid off the thumb, a map pan ended on every
    /// tile crossing, and a split-pane drag ended on its first motion.
    /// `dragenter`/`dragleave` DO bubble in the `W3C` model and keep doing so.
    #[must_use]
    pub const fn bubbles(self) -> bool {
        !matches!(
            self,
            Self::MouseEnter | Self::MouseLeave | Self::PenEnter | Self::PenLeave
        )
    }
}

/// Process a single propagation phase (Capture or Bubble)
fn propagate_phase(
    event: &mut SyntheticEvent,
    nodes: impl Iterator<Item = NodeId>,
    phase: EventPhase,
    callbacks: &BTreeMap<NodeId, Vec<EventFilter>>,
    result: &mut PropagationResult,
) {
    event.phase = phase;

    for node_id in nodes {
        if event.stopped_immediate || event.stopped {
            return;
        }

        event.current_target = DomNodeId {
            dom: event.target.dom,
            node: NodeHierarchyItemId::from_crate_internal(Some(node_id)),
        };

        collect_matching_callbacks(event, node_id, phase, callbacks, result);
    }
}

/// Process the target phase
fn propagate_target_phase(
    event: &mut SyntheticEvent,
    target_node_id: NodeId,
    callbacks: &BTreeMap<NodeId, Vec<EventFilter>>,
    result: &mut PropagationResult,
) {
    event.phase = EventPhase::Target;
    event.current_target = event.target;

    collect_matching_callbacks(event, target_node_id, EventPhase::Target, callbacks, result);
}

/// Collect callbacks that match the current phase for a node
fn collect_matching_callbacks(
    event: &SyntheticEvent,
    node_id: NodeId,
    phase: EventPhase,
    callbacks: &BTreeMap<NodeId, Vec<EventFilter>>,
    result: &mut PropagationResult,
) {
    let Some(node_callbacks) = callbacks.get(&node_id) else {
        return;
    };

    let matching = node_callbacks
        .iter()
        .take_while(|_| !event.stopped_immediate)
        .filter(|filter| matches_filter_phase(**filter, event, phase))
        .map(|filter| (node_id, *filter));

    result.callbacks_to_invoke.extend(matching);
}

// =============================================================================
// DEFAULT ACTIONS (W3C UI Events / HTML5 Activation Behavior)
// =============================================================================

/// Default actions are built-in behaviors that occur in response to events.
///
/// Per W3C DOM Event specification:
/// > A default action is an action that the implementation is expected to take
/// > in response to an event, unless that action is cancelled by the script.
///
/// Examples:
/// - Tab key → move focus to next focusable element
/// - Enter/Space on button → activate (click) the button
/// - Escape → clear focus or close modal
/// - Arrow keys in listbox → move selection
///
/// Default actions are processed AFTER all event callbacks have been invoked,
/// and only if `event.prevent_default()` was NOT called.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(C, u8)]
pub enum DefaultAction {
    /// Move focus to the next focusable element (Tab key)
    FocusNext,
    /// Move focus to the previous focusable element (Shift+Tab)
    FocusPrevious,
    /// Move focus to the first focusable element
    FocusFirst,
    /// Move focus to the last focusable element
    FocusLast,
    /// Move focus SPATIALLY — to the nearest focusable element in that
    /// direction, rather than the next one in document order.
    ///
    /// Tab order is a single sequence; a D-pad, a TV remote and spatial
    /// navigation all ask a different question ("what is above this?"), which
    /// `FocusTarget::Directional` already answered and nothing could request.
    ///
    /// NOT bound to the arrow keys: those scroll, and taking them
    /// unconditionally would break every scroll container. That binding waits
    /// on the CSS opt-out (item 9a-i); a D-pad has no such conflict.
    FocusUp,
    FocusDown,
    FocusLeft,
    FocusRight,
    /// Clear focus from the currently focused element (Escape key)
    ClearFocus,
    /// Activate the focused element (Enter/Space on activatable elements)
    /// This generates a synthetic Click event on the target
    ActivateFocusedElement { target: DomNodeId },
    /// Submit the form containing the focused element (Enter in form input)
    SubmitForm { form_node: DomNodeId },
    /// Close the current modal/dialog (Escape key when modal is open)
    CloseModal { modal_node: DomNodeId },
    /// Scroll the focused scrollable container
    ScrollFocusedContainer {
        direction: ScrollDirection,
        amount: ScrollAmount,
    },
    /// Select all text in the focused text input (Ctrl+A / Cmd+A)
    SelectAllText,
    /// Enter in a contenteditable host: record a STRUCTURAL split-block
    /// changeset for the app to apply to its model (azul never mutates the
    /// DOM). Execution = `LayoutWindow::record_structural_default_action`.
    SplitBlockAtCursor { target: DomNodeId },
    /// Backspace at block start in a contenteditable host: record a
    /// merge-with-previous-block changeset (same record-only semantics).
    MergeWithPrevious { target: DomNodeId },
    /// Delete at block end in a contenteditable host: record a
    /// merge-with-next-block changeset (same record-only semantics).
    MergeWithNext { target: DomNodeId },
    /// No default action for this event
    None,
    /// Enter in a PLAIN-TEXT editing context (the editing host's computed
    /// `white-space` preserves newlines: pre / pre-wrap / break-spaces /
    /// pre-line), and Shift+Enter in ANY contenteditable host: insert a
    /// literal `"\n"` through the standard text-input pipeline (which brings
    /// veto, undo, and caret-follow along) instead of recording a structural
    /// block split. APPENDED at the enum tail for ABI stability.
    InsertLineBreakAtCursor { target: DomNodeId },
    /// Reset a form to its controls' default values (a `type="reset"` control
    /// was activated). APPENDED at the enum tail for ABI stability.
    ///
    /// The sibling of [`Self::SubmitForm`]: both name the FORM rather than the
    /// control that triggered them, because a reset handler belongs on the
    /// form and the button is an implementation detail of how the user asked.
    ResetForm { form_node: DomNodeId },
}

/// Amount to scroll for keyboard-based scrolling
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(C)]
pub enum ScrollAmount {
    /// Scroll by one line (arrow keys)
    Line,
    /// Scroll by one page (Page Up/Down)
    Page,
    /// Scroll to start/end (Home/End)
    Document,
}

/// Result of determining what default action should occur for an event.
///
/// This is computed AFTER event dispatch, based on:
/// 1. The event type
/// 2. The target element's type/role
/// 3. Whether `prevent_default()` was called
#[derive(Debug, Clone, Copy)]
#[repr(C)]
pub struct DefaultActionResult {
    /// The default action to perform (if any)
    pub action: DefaultAction,
    /// Whether the action was prevented by a callback
    pub prevented: bool,
}

impl Default for DefaultActionResult {
    fn default() -> Self {
        Self {
            action: DefaultAction::None,
            prevented: false,
        }
    }
}

impl DefaultActionResult {
    /// Create a new result with a specific action
    #[must_use]
    pub const fn new(action: DefaultAction) -> Self {
        Self {
            action,
            prevented: false,
        }
    }

    /// Create a prevented result (callback called `prevent_default`)
    #[must_use]
    pub const fn prevented() -> Self {
        Self {
            action: DefaultAction::None,
            prevented: true,
        }
    }

    /// Check if there's an action to perform
    #[must_use]
    pub const fn has_action(&self) -> bool {
        !self.prevented && !matches!(self.action, DefaultAction::None)
    }
}

/// Trait for elements that have activation behavior (can be "clicked" via keyboard).
///
/// Per HTML5 spec, elements with activation behavior include:
/// - `<button>` elements
/// - `<input type="submit">`, `<input type="button">`, `<input type="reset">`
/// - `<a>` elements with href
/// - `<area>` elements with href
/// - Any element with a click handler (implicit activation)
///
/// When an element with activation behavior is focused and the user presses
/// Enter or Space, a synthetic click event is generated.
pub trait ActivationBehavior {
    /// Returns true if this element can be activated via keyboard (Enter/Space)
    fn has_activation_behavior(&self) -> bool;

    /// Returns true if this element is currently activatable
    /// (e.g., not disabled, not aria-disabled="true")
    fn is_activatable(&self) -> bool;
}

/// Trait to query if a node is focusable for tab navigation
pub trait Focusable {
    /// Returns the tabindex value for this element (-1, 0, or positive)
    fn get_tabindex(&self) -> Option<i32>;

    /// Returns true if this element can receive focus
    fn is_focusable(&self) -> bool;

    /// Returns true if this element should be in the tab order
    fn is_in_tab_order(&self) -> bool {
        self.get_tabindex()
            .map_or_else(|| self.is_naturally_focusable(), |i| i >= 0)
    }

    /// Returns true if this element type is naturally focusable
    /// (button, input, select, textarea, a[href])
    fn is_naturally_focusable(&self) -> bool;
}

/// Check if an event filter matches the given event in the current phase.
///
/// This is used during event propagation to determine which callbacks
/// should be invoked at each phase.
fn matches_filter_phase(
    filter: EventFilter,
    event: &SyntheticEvent,
    current_phase: EventPhase,
) -> bool {

    // azul has no capture-phase listeners (no `addEventListener(…, capture=true)`
    // equivalent): every `EventFilter` is a bubble-phase listener, which by the W3C
    // model fires only in the Target and Bubble phases — never Capture. Without this
    // guard an ancestor node's Hover/Focus callback was collected in BOTH the capture
    // and the bubble walk, so it fired TWICE whenever the hit target was a descendant
    // (e.g. a menubar item, hit via its text child, opened two stacked popups; any
    // button containing a text/child node ran its MouseUp callback twice).
    if matches!(current_phase, EventPhase::Capture) {
        return false;
    }

    match filter {
        EventFilter::Hover(hover_filter) => {
            matches_hover_filter(hover_filter, event, current_phase)
        }
        EventFilter::Focus(focus_filter) => {
            matches_focus_filter(focus_filter, event, current_phase)
        }
        EventFilter::Window(window_filter) => {
            matches_window_filter(window_filter, event, current_phase)
        }
        EventFilter::Component(component_filter) => {
            matches_component_filter(component_filter, event, current_phase)
        }
        EventFilter::Application(application_filter) => {
            matches_application_filter(application_filter, event, current_phase)
        }
        EventFilter::External(external_filter) => {
            matches_external_filter(external_filter, event, current_phase)
        }
    }
}

/// Check if a component (lifecycle) filter matches the event.
///
/// Lifecycle events produced by `diff::reconcile_dom` carry the target node in
/// `SyntheticEvent.target`, so dispatchers that bypass `propagate_event` and
/// invoke the target directly also need a way to compare. This predicate is
/// the single source of truth for that comparison; changing it without
/// updating `event_type_to_filters` will de-sync dispatch.
const fn matches_component_filter(
    filter: ComponentEventFilter,
    event: &SyntheticEvent,
    _phase: EventPhase,
) -> bool {
    matches!(
        (filter, &event.event_type),
        (ComponentEventFilter::AfterMount, EventType::Mount)
            | (ComponentEventFilter::BeforeUnmount, EventType::Unmount)
            | (ComponentEventFilter::Updated, EventType::Update)
            | (ComponentEventFilter::NodeResized, EventType::Resize)
            | (ComponentEventFilter::Dismissed, EventType::Dismiss)
            | (ComponentEventFilter::TornOff, EventType::TearOff)
            | (ComponentEventFilter::Docked, EventType::Dock)
            // These two were simply absent from the match. Both filter
            // variants shipped in `ComponentEventFilter`, so a component
            // subscribing to either was collected and then dropped.
            | (ComponentEventFilter::DefaultAction, EventType::DefaultAction)
            | (ComponentEventFilter::Selected, EventType::Selected)
    )
}

/// Check if the event data contains a mouse event with the expected button.
/// `MouseButton::Other(BACK)` — the thumb "back" button, button 4 on a mouse
/// and index 3 zero-based, which is the numbering the web and every shell
/// already use (Win32 `XBUTTON1`, X11 button 8, macOS `otherMouseDown:` 3).
pub const MOUSE_BUTTON_BACK: u8 = 3;
/// `MouseButton::Other(FORWARD)` — the thumb "forward" button.
pub const MOUSE_BUTTON_FORWARD: u8 = 4;

/// Bit for the back button in [`MouseState::other_down`].
pub const MOUSE_OTHER_MASK_BACK: u8 = 1 << 0;
/// Bit for the forward button in [`MouseState::other_down`].
pub const MOUSE_OTHER_MASK_FORWARD: u8 = 1 << 1;

fn check_mouse_button(data: &EventData, expected: MouseButton) -> bool {
    if let EventData::Mouse(mouse_data) = data {
        mouse_data.button == expected
    } else {
        false
    }
}

/// Check if a hover filter matches the event.
// Exhaustive (filter, event-type) truth table: many distinct pairs share the
// `=> true` body. One arm per pair is intentional; merging into giant or-patterns
// would destroy the table's readability/maintainability.
#[allow(clippy::match_same_arms)]
fn matches_hover_filter(
    filter: HoverEventFilter,
    event: &SyntheticEvent,
    _phase: EventPhase,
) -> bool {
    use HoverEventFilter::{
        BiometricResult, DoubleClick, Drag, DragEnd, DragEnter, DragLeave, DragOver, DragStart,
        Drop, DroppedFile, GamepadInput, GeolocationError, GeolocationFix, HoveredFile,
        HoveredFileCancelled, KeyringResult, LeftMouseDown, LeftMouseUp, MiddleMouseDown,
        MiddleMouseUp, MouseDown, MouseEnter, MouseLeave, MouseMove, MouseOver, MouseUp,
        PenDoubleTap, PenDown,
        PenEnter, PenHover, PenLeave, PenMove, PenSqueeze, PenUp, PermissionChanged, RightMouseDown,
        RightMouseUp,
        ScreenColorPicked, Scroll, ScrollEnd, ScrollStart, SensorChanged, TextInput, TouchCancel,
        TouchEnd, TouchMove, TouchStart, VirtualKeyDown, VirtualKeyUp,
    };

    match (filter, &event.event_type) {
        (MouseOver, EventType::MouseOver) => true,
        (MouseMove, EventType::MouseMove) => true,
        (MouseDown, EventType::MouseDown) => true,
        (LeftMouseDown, EventType::MouseDown) => check_mouse_button(&event.data, MouseButton::Left),
        (RightMouseDown, EventType::MouseDown) => {
            check_mouse_button(&event.data, MouseButton::Right)
        }
        (MiddleMouseDown, EventType::MouseDown) => {
            check_mouse_button(&event.data, MouseButton::Middle)
        }
        (MouseUp, EventType::MouseUp) => true,
        // KEYBOARD ACTIVATION (Enter / Space on a focused element) dispatches
        // a synthetic `EventType::Click`. Every widget in the toolkit listens
        // on MouseUp / LeftMouseUp - the pointer spelling of "activate" - so
        // without this arm the synthetic event matched NOTHING and Enter /
        // Space silently did nothing on every focusable widget (device
        // report, 2026-08-31). Nothing else in the engine emits
        // `EventType::Click`, so this cannot double-fire a real pointer
        // click: a real click arrives as MouseDown + MouseUp.
        //
        // A keyboard activation counts as a LEFT activation - it carries no
        // button data, so `check_mouse_button` cannot answer for it - which
        // is the W3C activation behaviour Enter and Space implement.
        (HoverEventFilter::Click, EventType::Click) => true,
        (LeftMouseUp, EventType::MouseUp) => check_mouse_button(&event.data, MouseButton::Left),
        (RightMouseUp, EventType::MouseUp) => check_mouse_button(&event.data, MouseButton::Right),
        (MiddleMouseUp, EventType::MouseUp) => check_mouse_button(&event.data, MouseButton::Middle),
        (MouseEnter, EventType::MouseEnter) => true,
        (MouseLeave, EventType::MouseLeave) => true,
        (Scroll, EventType::Scroll) => true,
        (ScrollStart, EventType::ScrollStart) => true,
        (ScrollEnd, EventType::ScrollEnd) => true,
        (TextInput, EventType::Input) => true,
        // `KeyPress` (a key that produced a character) and `Change` (a value
        // committed on blur) both plan onto the `TextInput` filter, which is
        // what an app registers for "text arrived here". Planning named that
        // filter and this table then rejected it, so both dispatched to
        // nothing.
        (TextInput, EventType::KeyPress) => true,
        (TextInput, EventType::Change) => true,
        // A context-menu request is not a `MouseDown`, so the button-payload
        // check on the `RightMouseDown` arm cannot answer for it. Routing it
        // to the same filter means the Menu/Apps key, Shift+F10 and the
        // accessibility `ShowContextMenu` action all reach the handler an app
        // already registered for right-click, without inventing a new filter
        // variant for each spelling of "open the context menu".
        (RightMouseDown, EventType::ContextMenu) => true,
        (VirtualKeyDown, EventType::KeyDown) => true,
        (VirtualKeyUp, EventType::KeyUp) => true,
        (HoveredFile, EventType::FileHover) => true,
        (DroppedFile, EventType::FileDrop) => true,
        (HoveredFileCancelled, EventType::FileHoverCancel) => true,
        (TouchStart, EventType::TouchStart) => true,
        (TouchMove, EventType::TouchMove) => true,
        (TouchEnd, EventType::TouchEnd) => true,
        (TouchCancel, EventType::TouchCancel) => true,
        (PenDown, EventType::PenDown) => true,
        (PenMove, EventType::PenMove) => true,
        (PenUp, EventType::PenUp) => true,
        (PenEnter, EventType::PenEnter) => true,
        (PenLeave, EventType::PenLeave) => true,
        (DragStart, EventType::DragStart) => true,
        (Drag, EventType::Drag) => true,
        (DragEnd, EventType::DragEnd) => true,
        (DragEnter, EventType::DragEnter) => true,
        (DragOver, EventType::DragOver) => true,
        (DragLeave, EventType::DragLeave) => true,
        (Drop, EventType::Drop) => true,
        (DoubleClick, EventType::DoubleClick) => true,
        (SensorChanged, EventType::SensorChanged) => true,
        (GamepadInput, EventType::GamepadInput) => true,
        (GeolocationFix, EventType::GeolocationFix) => true,
        (GeolocationError, EventType::GeolocationError) => true,
        (PermissionChanged, EventType::PermissionChanged) => true,
        (BiometricResult, EventType::BiometricResult) => true,
        (ScreenColorPicked, EventType::ScreenColorPicked) => true,
        (KeyringResult, EventType::KeyringResult) => true,
        // Gestures. These filters existed, the detectors produced the events,
        // and this table had no arm for them — a `PinchOut` handler on a map
        // could never fire, whatever the gesture manager saw.
        (HoverEventFilter::LongPress, EventType::LongPress) => true,
        (HoverEventFilter::SwipeLeft, EventType::SwipeLeft) => true,
        (HoverEventFilter::SwipeRight, EventType::SwipeRight) => true,
        (HoverEventFilter::SwipeUp, EventType::SwipeUp) => true,
        (HoverEventFilter::SwipeDown, EventType::SwipeDown) => true,
        (HoverEventFilter::PinchIn, EventType::PinchIn) => true,
        (HoverEventFilter::PinchOut, EventType::PinchOut) => true,
        (HoverEventFilter::RotateClockwise, EventType::RotateClockwise) => true,
        (HoverEventFilter::RotateCounterClockwise, EventType::RotateCounterClockwise) => true,
        (HoverEventFilter::MouseOut, EventType::MouseOut) => true,
        (HoverEventFilter::FocusIn, EventType::FocusIn) => true,
        (HoverEventFilter::FocusOut, EventType::FocusOut) => true,
        (HoverEventFilter::CompositionStart, EventType::CompositionStart) => true,
        (HoverEventFilter::CompositionUpdate, EventType::CompositionUpdate) => true,
        (HoverEventFilter::CompositionEnd, EventType::CompositionEnd) => true,
        // Pen barrel gestures and hover. The filter variants shipped long
        // before any `EventType` existed that could reach them.
        (PenSqueeze, EventType::PenSqueeze) => true,
        (PenDoubleTap, EventType::PenDoubleTap) => true,
        (PenHover, EventType::PenHover) => true,
        // Thumb buttons. Gated on the payload like every other
        // button-specific arm — a payloadless event must not claim a button.
        (HoverEventFilter::BackMouseDown, EventType::MouseDown) => {
            check_mouse_button(&event.data, MouseButton::Other(MOUSE_BUTTON_BACK))
        }
        (HoverEventFilter::BackMouseUp, EventType::MouseUp) => {
            check_mouse_button(&event.data, MouseButton::Other(MOUSE_BUTTON_BACK))
        }
        (HoverEventFilter::ForwardMouseDown, EventType::MouseDown) => {
            check_mouse_button(&event.data, MouseButton::Other(MOUSE_BUTTON_FORWARD))
        }
        (HoverEventFilter::ForwardMouseUp, EventType::MouseUp) => {
            check_mouse_button(&event.data, MouseButton::Other(MOUSE_BUTTON_FORWARD))
        }
        (HoverEventFilter::Submit, EventType::Submit) => true,
        (HoverEventFilter::Change, EventType::Change) => true,
        (HoverEventFilter::Reset, EventType::Reset) => true,
        (HoverEventFilter::Invalid, EventType::Invalid) => true,
        // The dial. A NODE-scoped dial event only makes sense for a device
        // that reports a contact point (a Surface Dial ON the display); every
        // other dial reaches the app through the Window filter.
        (HoverEventFilter::DialRotate, EventType::DialRotate) => true,
        (HoverEventFilter::DialClick, EventType::DialClick) => true,
        _ => false,
    }
}

/// Check if a focus filter matches the event.
// Exhaustive (filter, event-type) truth table — see matches_hover_filter.
#[allow(clippy::match_same_arms)]
fn matches_focus_filter(
    filter: FocusEventFilter,
    event: &SyntheticEvent,
    _phase: EventPhase,
) -> bool {
    use FocusEventFilter::{
        Drag, DragEnd, DragEnter, DragLeave, DragOver, DragStart, Drop, FocusLost, FocusReceived,
        LeftMouseDown, LeftMouseUp, MiddleMouseDown, MiddleMouseUp, MouseDown, MouseEnter,
        MouseLeave, MouseMove, MouseOver, MouseUp, RightMouseDown, RightMouseUp, Scroll, ScrollEnd,
        ScrollStart, TextInput, VirtualKeyDown, VirtualKeyUp,
    };

    match (filter, &event.event_type) {
        (MouseOver, EventType::MouseOver) => true,
        (MouseMove, EventType::MouseMove) => true,
        (MouseDown, EventType::MouseDown) => true,
        (LeftMouseDown, EventType::MouseDown) => check_mouse_button(&event.data, MouseButton::Left),
        (RightMouseDown, EventType::MouseDown) => {
            check_mouse_button(&event.data, MouseButton::Right)
        }
        (MiddleMouseDown, EventType::MouseDown) => {
            check_mouse_button(&event.data, MouseButton::Middle)
        }
        (MouseUp, EventType::MouseUp) => true,
        (LeftMouseUp, EventType::MouseUp) => check_mouse_button(&event.data, MouseButton::Left),
        (RightMouseUp, EventType::MouseUp) => check_mouse_button(&event.data, MouseButton::Right),
        (MiddleMouseUp, EventType::MouseUp) => check_mouse_button(&event.data, MouseButton::Middle),
        (MouseEnter, EventType::MouseEnter) => true,
        (MouseLeave, EventType::MouseLeave) => true,
        (Scroll, EventType::Scroll) => true,
        (ScrollStart, EventType::ScrollStart) => true,
        (ScrollEnd, EventType::ScrollEnd) => true,
        (TextInput, EventType::Input) => true,
        (FocusEventFilter::DocumentEdit, EventType::DocumentEdit) => true,
        (FocusEventFilter::TextChanged, EventType::TextChanged) => true,
        (VirtualKeyDown, EventType::KeyDown) => true,
        (VirtualKeyUp, EventType::KeyUp) => true,
        (FocusReceived, EventType::Focus) => true,
        (FocusLost, EventType::Blur) => true,
        (DragStart, EventType::DragStart) => true,
        (Drag, EventType::Drag) => true,
        (DragEnd, EventType::DragEnd) => true,
        (DragEnter, EventType::DragEnter) => true,
        (DragOver, EventType::DragOver) => true,
        (DragLeave, EventType::DragLeave) => true,
        (Drop, EventType::Drop) => true,
        // MWA-C-clipboard: W3C clipboard events on the focused element
        // (qualified paths — `use FocusEventFilter::Copy` would shadow the
        // `Copy` trait in this scope).
        (FocusEventFilter::Copy, EventType::Copy) => true,
        (FocusEventFilter::Cut, EventType::Cut) => true,
        (FocusEventFilter::Paste, EventType::Paste) => true,
        // Gestures — same gap as the hover table.
        (FocusEventFilter::LongPress, EventType::LongPress) => true,
        (FocusEventFilter::SwipeLeft, EventType::SwipeLeft) => true,
        (FocusEventFilter::SwipeRight, EventType::SwipeRight) => true,
        (FocusEventFilter::SwipeUp, EventType::SwipeUp) => true,
        (FocusEventFilter::SwipeDown, EventType::SwipeDown) => true,
        (FocusEventFilter::PinchIn, EventType::PinchIn) => true,
        (FocusEventFilter::PinchOut, EventType::PinchOut) => true,
        (FocusEventFilter::RotateClockwise, EventType::RotateClockwise) => true,
        (FocusEventFilter::RotateCounterClockwise, EventType::RotateCounterClockwise) => true,
        // Pen — `FocusEventFilter` has carried Down/Move/Up since the filter
        // was introduced, but this table had no arm for any of them, so a
        // focused node could never receive a pen event even once dispatch
        // planning named the filter. (Enter/Leave have no Focus twin: a pen
        // crossing a node's bounds is not a focus change.)
        (FocusEventFilter::PenDown, EventType::PenDown) => true,
        (FocusEventFilter::PenMove, EventType::PenMove) => true,
        (FocusEventFilter::PenUp, EventType::PenUp) => true,
        // Thumb buttons. Gated on the payload like every other
        // button-specific arm — a payloadless event must not claim a button.
        (FocusEventFilter::BackMouseDown, EventType::MouseDown) => {
            check_mouse_button(&event.data, MouseButton::Other(MOUSE_BUTTON_BACK))
        }
        (FocusEventFilter::BackMouseUp, EventType::MouseUp) => {
            check_mouse_button(&event.data, MouseButton::Other(MOUSE_BUTTON_BACK))
        }
        (FocusEventFilter::ForwardMouseDown, EventType::MouseDown) => {
            check_mouse_button(&event.data, MouseButton::Other(MOUSE_BUTTON_FORWARD))
        }
        (FocusEventFilter::ForwardMouseUp, EventType::MouseUp) => {
            check_mouse_button(&event.data, MouseButton::Other(MOUSE_BUTTON_FORWARD))
        }
        (FocusEventFilter::Submit, EventType::Submit) => true,
        (FocusEventFilter::Change, EventType::Change) => true,
        (FocusEventFilter::Reset, EventType::Reset) => true,
        (FocusEventFilter::Invalid, EventType::Invalid) => true,
        _ => false,
    }
}

/// Check if an application filter matches the event.
///
/// Application events are not hit-tested and have no meaningful target: a
/// device arriving or a monitor being unplugged belongs to the application,
/// not to whichever node happened to be under the cursor. They are dispatched
/// at the root and reach any subscriber by propagation, which is why this
/// table ignores the phase exactly as the window table does.
///
/// This arm returned a flat `false` — "will be implemented in future" — so all
/// four variants were structurally unreachable no matter what a shell emitted.
/// Every other layer was already in place: `event_type_to_filters` had named
/// `EF::Application(..)` for the monitor pair the whole time.
// Exhaustive (filter, event-type) truth table — see matches_hover_filter.
#[allow(clippy::match_same_arms)]
fn matches_application_filter(
    filter: ApplicationEventFilter,
    event: &SyntheticEvent,
    _phase: EventPhase,
) -> bool {
    use ApplicationEventFilter::{
        DeviceConnected, DeviceDisconnected, MediaControl, MonitorConnected, MonitorDisconnected,
        SystemAudioChange,
    };

    match (filter, &event.event_type) {
        (MediaControl, EventType::MediaControl) => true,
        (SystemAudioChange, EventType::SystemAudioChange) => true,
        (DeviceConnected, EventType::DeviceConnected) => true,
        (DeviceDisconnected, EventType::DeviceDisconnected) => true,
        (MonitorConnected, EventType::MonitorConnected) => true,
        (MonitorDisconnected, EventType::MonitorDisconnected) => true,
        _ => false,
    }
}

/// Check if an external filter matches the event (11c).
///
/// Media events are not hit-tested: the player is not a device with a
/// position, so there is no node "under" a `TimeUpdate`. Like the window and
/// application tables this therefore ignores the phase; the event's `target`
/// still names the media node, for callbacks that serve more than one.
// Exhaustive (filter, event-type) truth table — see matches_hover_filter.
#[allow(clippy::match_same_arms)]
const fn matches_external_filter(
    filter: ExternalEventFilter,
    event: &SyntheticEvent,
    _phase: EventPhase,
) -> bool {
    matches!(
        (filter, &event.event_type),
        (ExternalEventFilter::Play, EventType::Play)
            | (ExternalEventFilter::Pause, EventType::Pause)
            | (ExternalEventFilter::Ended, EventType::Ended)
            | (ExternalEventFilter::TimeUpdate, EventType::TimeUpdate)
            | (ExternalEventFilter::VolumeChange, EventType::VolumeChange)
            | (ExternalEventFilter::MediaError, EventType::MediaError)
    )
}

/// Check if a window filter matches the event.
// Exhaustive (filter, event-type) truth table — see matches_hover_filter.
#[allow(clippy::match_same_arms)]
fn matches_window_filter(
    filter: WindowEventFilter,
    event: &SyntheticEvent,
    _phase: EventPhase,
) -> bool {
    use WindowEventFilter::{
        BiometricResult, CloseRequested, Drag, DragEnd, DragEnter, DragLeave, DragOver, DragStart,
        Drop, DroppedFile, FocusLost, FocusReceived, FrameChanged, GamepadInput, GeolocationError,
        GeolocationFix, HoveredFile, HoveredFileCancelled, KeyringResult, LeftMouseDown,
        LeftMouseUp, MiddleMouseDown, MiddleMouseUp, MouseDown, MouseEnter, MouseLeave, MouseMove,
        MouseOver,
        MouseUp, Moved, PenDoubleTap, PenDown, PenEnter, PenHover, PenLeave, PenMove, PenSqueeze,
        ModifiersChanged, PenUp, PermissionChanged, PointerLockChange, RawMouseMotion, Resized,
        RightMouseDown, RightMouseUp, ScreenColorPicked, Scroll, ScrollEnd, ScrollStart,
        SensorChanged, TextInput, ThemeChanged, TouchCancel, TouchEnd, TouchMove, TouchStart,
        VirtualKeyDown, VirtualKeyUp, WindowFocusLost, WindowFocusReceived,
    };

    match (filter, &event.event_type) {
        (MouseOver, EventType::MouseOver) => true,
        (MouseMove, EventType::MouseMove) => true,
        (MouseDown, EventType::MouseDown) => true,
        (LeftMouseDown, EventType::MouseDown) => check_mouse_button(&event.data, MouseButton::Left),
        (RightMouseDown, EventType::MouseDown) => {
            check_mouse_button(&event.data, MouseButton::Right)
        }
        (MiddleMouseDown, EventType::MouseDown) => {
            check_mouse_button(&event.data, MouseButton::Middle)
        }
        (MouseUp, EventType::MouseUp) => true,
        (LeftMouseUp, EventType::MouseUp) => check_mouse_button(&event.data, MouseButton::Left),
        (RightMouseUp, EventType::MouseUp) => check_mouse_button(&event.data, MouseButton::Right),
        (MiddleMouseUp, EventType::MouseUp) => check_mouse_button(&event.data, MouseButton::Middle),
        (MouseEnter, EventType::MouseEnter) => true,
        (MouseLeave, EventType::MouseLeave) => true,
        (Scroll, EventType::Scroll) => true,
        (ScrollStart, EventType::ScrollStart) => true,
        (ScrollEnd, EventType::ScrollEnd) => true,
        (TextInput, EventType::Input) => true,
        // `KeyPress` (a key that produced a character) and `Change` (a value
        // committed on blur) both plan onto the `TextInput` filter, which is
        // what an app registers for "text arrived here". Planning named that
        // filter and this table then rejected it, so both dispatched to
        // nothing.
        (TextInput, EventType::KeyPress) => true,
        (TextInput, EventType::Change) => true,
        // A context-menu request is not a `MouseDown`, so the button-payload
        // check on the `RightMouseDown` arm cannot answer for it. Routing it
        // to the same filter means the Menu/Apps key, Shift+F10 and the
        // accessibility `ShowContextMenu` action all reach the handler an app
        // already registered for right-click, without inventing a new filter
        // variant for each spelling of "open the context menu".
        (RightMouseDown, EventType::ContextMenu) => true,
        (VirtualKeyDown, EventType::KeyDown) => true,
        (VirtualKeyUp, EventType::KeyUp) => true,
        (HoveredFile, EventType::FileHover) => true,
        (DroppedFile, EventType::FileDrop) => true,
        (HoveredFileCancelled, EventType::FileHoverCancel) => true,
        (Resized, EventType::WindowResize) => true,
        (FrameChanged, EventType::WindowFrameChanged) => true,
        (Moved, EventType::WindowMove) => true,
        (TouchStart, EventType::TouchStart) => true,
        (TouchMove, EventType::TouchMove) => true,
        (TouchEnd, EventType::TouchEnd) => true,
        (TouchCancel, EventType::TouchCancel) => true,
        (PenDown, EventType::PenDown) => true,
        (PenMove, EventType::PenMove) => true,
        (PenUp, EventType::PenUp) => true,
        (PenEnter, EventType::PenEnter) => true,
        (PenLeave, EventType::PenLeave) => true,
        (FocusReceived, EventType::Focus) => true,
        (FocusLost, EventType::Blur) => true,
        (CloseRequested, EventType::WindowClose) => true,
        (ThemeChanged, EventType::ThemeChange) => true,
        (WindowFocusReceived, EventType::WindowFocusIn) => true,
        (WindowFocusLost, EventType::WindowFocusOut) => true,
        (PointerLockChange, EventType::PointerLockChange) => true,
        (SensorChanged, EventType::SensorChanged) => true,
        (GamepadInput, EventType::GamepadInput) => true,
        (GeolocationFix, EventType::GeolocationFix) => true,
        (GeolocationError, EventType::GeolocationError) => true,
        (PermissionChanged, EventType::PermissionChanged) => true,
        (BiometricResult, EventType::BiometricResult) => true,
        (ScreenColorPicked, EventType::ScreenColorPicked) => true,
        (KeyringResult, EventType::KeyringResult) => true,
        (DragStart, EventType::DragStart) => true,
        (Drag, EventType::Drag) => true,
        (DragEnd, EventType::DragEnd) => true,
        (DragEnter, EventType::DragEnter) => true,
        (DragOver, EventType::DragOver) => true,
        (DragLeave, EventType::DragLeave) => true,
        (Drop, EventType::Drop) => true,
        // Gestures — same gap as the hover table.
        (WindowEventFilter::LongPress, EventType::LongPress) => true,
        (WindowEventFilter::SwipeLeft, EventType::SwipeLeft) => true,
        (WindowEventFilter::SwipeRight, EventType::SwipeRight) => true,
        (WindowEventFilter::SwipeUp, EventType::SwipeUp) => true,
        (WindowEventFilter::SwipeDown, EventType::SwipeDown) => true,
        (WindowEventFilter::PinchIn, EventType::PinchIn) => true,
        (WindowEventFilter::PinchOut, EventType::PinchOut) => true,
        (WindowEventFilter::RotateClockwise, EventType::RotateClockwise) => true,
        (WindowEventFilter::RotateCounterClockwise, EventType::RotateCounterClockwise) => true,
        // Pen barrel gestures and hover. The filter variants shipped long
        // before any `EventType` existed that could reach them.
        (PenSqueeze, EventType::PenSqueeze) => true,
        (PenDoubleTap, EventType::PenDoubleTap) => true,
        (PenHover, EventType::PenHover) => true,
        // Thumb buttons. Gated on the payload like every other
        // button-specific arm — a payloadless event must not claim a button.
        (WindowEventFilter::BackMouseDown, EventType::MouseDown) => {
            check_mouse_button(&event.data, MouseButton::Other(MOUSE_BUTTON_BACK))
        }
        (WindowEventFilter::BackMouseUp, EventType::MouseUp) => {
            check_mouse_button(&event.data, MouseButton::Other(MOUSE_BUTTON_BACK))
        }
        (WindowEventFilter::ForwardMouseDown, EventType::MouseDown) => {
            check_mouse_button(&event.data, MouseButton::Other(MOUSE_BUTTON_FORWARD))
        }
        (WindowEventFilter::ForwardMouseUp, EventType::MouseUp) => {
            check_mouse_button(&event.data, MouseButton::Other(MOUSE_BUTTON_FORWARD))
        }
        (RawMouseMotion, EventType::RawMouseMotion) => true,
        (ModifiersChanged, EventType::ModifiersChanged) => true,
        (WindowEventFilter::HidReport, EventType::HidReport) => true,
        (WindowEventFilter::DialRotate, EventType::DialRotate) => true,
        (WindowEventFilter::DialClick, EventType::DialClick) => true,
        // Media (11c). These six `EventType`s shipped with no filter in ANY
        // family, so they planned an empty list and dispatched to nothing.
        (WindowEventFilter::Play, EventType::Play) => true,
        (WindowEventFilter::Pause, EventType::Pause) => true,
        (WindowEventFilter::Ended, EventType::Ended) => true,
        (WindowEventFilter::TimeUpdate, EventType::TimeUpdate) => true,
        (WindowEventFilter::VolumeChange, EventType::VolumeChange) => true,
        (WindowEventFilter::MediaError, EventType::MediaError) => true,
        _ => false,
    }
}

/// Detect lifecycle events by comparing old and new DOM state.
///
/// This is the simple, index-based lifecycle detection that doesn't account for
/// node reordering. For more sophisticated reconciliation that can detect moves,
/// use `detect_lifecycle_events_with_reconciliation`.
///
/// Generates Mount, Unmount, and Resize events by comparing DOM hierarchies.
#[allow(clippy::needless_pass_by_value)] // owned azul value taken by value (public API / ownership-transfer convention)
#[must_use]
pub fn detect_lifecycle_events(
    old_dom_id: DomId,
    new_dom_id: DomId,
    old_hierarchy: Option<&crate::id::NodeHierarchy>,
    new_hierarchy: Option<&crate::id::NodeHierarchy>,
    old_layout: Option<&BTreeMap<NodeId, LogicalRect>>,
    new_layout: Option<&BTreeMap<NodeId, LogicalRect>>,
    timestamp: Instant,
) -> Vec<SyntheticEvent> {
    let old_nodes = collect_node_ids(old_hierarchy);
    let new_nodes = collect_node_ids(new_hierarchy);

    let mut events = Vec::new();

    // Mount events: nodes in new but not in old
    if let Some(layout) = new_layout {
        for &node_id in new_nodes.difference(&old_nodes) {
            events.push(create_mount_event(node_id, new_dom_id, layout, &timestamp));
        }
    }

    // Unmount events: nodes in old but not in new
    if let Some(layout) = old_layout {
        for &node_id in old_nodes.difference(&new_nodes) {
            events.push(create_unmount_event(
                node_id, old_dom_id, layout, &timestamp,
            ));
        }
    }

    // Resize events: nodes in both with changed bounds
    if let (Some(old_l), Some(new_l)) = (old_layout, new_layout) {
        for &node_id in old_nodes.intersection(&new_nodes) {
            if let Some(ev) = create_resize_event(node_id, new_dom_id, old_l, new_l, &timestamp) {
                events.push(ev);
            }
        }
    }

    events
}

fn collect_node_ids(hierarchy: Option<&crate::id::NodeHierarchy>) -> BTreeSet<NodeId> {
    hierarchy
        .map(|h| h.as_ref().linear_iter().collect())
        .unwrap_or_default()
}

fn create_lifecycle_event(
    event_type: EventType,
    node_id: NodeId,
    dom_id: DomId,
    timestamp: &Instant,
    data: LifecycleEventData,
) -> SyntheticEvent {
    let dom_node_id = DomNodeId {
        dom: dom_id,
        node: NodeHierarchyItemId::from_crate_internal(Some(node_id)),
    };
    SyntheticEvent {
        event_type,
        source: EventSource::Lifecycle,
        phase: EventPhase::Target,
        target: dom_node_id,
        current_target: dom_node_id,
        timestamp: timestamp.clone(),
        data: EventData::Lifecycle(data),
        stopped: false,
        stopped_immediate: false,
        prevented_default: false,
        at_target_only: false,
    }
}

fn create_mount_event(
    node_id: NodeId,
    dom_id: DomId,
    layout: &BTreeMap<NodeId, LogicalRect>,
    timestamp: &Instant,
) -> SyntheticEvent {
    let current_bounds = layout.get(&node_id).copied().unwrap_or(LogicalRect::zero());
    create_lifecycle_event(
        EventType::Mount,
        node_id,
        dom_id,
        timestamp,
        LifecycleEventData {
            reason: LifecycleReason::InitialMount,
            previous_bounds: None,
            current_bounds,
        },
    )
}

fn create_unmount_event(
    node_id: NodeId,
    dom_id: DomId,
    layout: &BTreeMap<NodeId, LogicalRect>,
    timestamp: &Instant,
) -> SyntheticEvent {
    let previous_bounds = layout.get(&node_id).copied().unwrap_or(LogicalRect::zero());
    create_lifecycle_event(
        EventType::Unmount,
        node_id,
        dom_id,
        timestamp,
        LifecycleEventData {
            reason: LifecycleReason::Unmount,
            previous_bounds: Some(previous_bounds),
            current_bounds: LogicalRect::zero(),
        },
    )
}

/// Returns `true` iff the two logical sizes differ after fixed-point
/// quantization (~0.001 tolerance), treating a dimension that is NaN on *both*
/// sides as unchanged so a degenerate layout cannot emit a Resize every frame.
fn size_changed(old: crate::geom::LogicalSize, new: crate::geom::LogicalSize) -> bool {
    fn dim_changed(a: f32, b: f32) -> bool {
        if a.is_nan() && b.is_nan() {
            return false;
        }
        // Fixed-point quantization mirrors `LogicalSize`'s `Ord`/`Hash`.
        // `f32 as i64` saturates on overflow (no wasm32 wraparound); a lone
        // NaN quantizes to `i64::MIN` and so registers as changed.
        #[allow(clippy::cast_possible_truncation)]
        // intentional fixed-point quantization; saturates
        let q = |v: f32| -> i64 {
            if v.is_nan() {
                i64::MIN
            } else {
                (v * 1000.0) as i64
            }
        };
        q(a) != q(b)
    }
    dim_changed(old.width, new.width) || dim_changed(old.height, new.height)
}

fn create_resize_event(
    node_id: NodeId,
    dom_id: DomId,
    old_layout: &BTreeMap<NodeId, LogicalRect>,
    new_layout: &BTreeMap<NodeId, LogicalRect>,
    timestamp: &Instant,
) -> Option<SyntheticEvent> {
    let old_bounds = *old_layout.get(&node_id)?;
    let new_bounds = *new_layout.get(&node_id)?;

    // Quantized/tolerance compare with an explicit NaN guard. A raw `==` on
    // `LogicalSize` used to compare f32 bit patterns, so a single NaN dimension
    // made `old != new` true *every frame forever* -> an endless Resize-event
    // loop. `size_changed` treats a NaN dimension present on both sides as
    // "unchanged" and otherwise compares fixed-point-quantized values.
    if !size_changed(old_bounds.size, new_bounds.size) {
        return None;
    }

    Some(create_lifecycle_event(
        EventType::Resize,
        node_id,
        dom_id,
        timestamp,
        LifecycleEventData {
            reason: LifecycleReason::Resize,
            previous_bounds: Some(old_bounds),
            current_bounds: new_bounds,
        },
    ))
}

/// A `Resize` lifecycle event (`ComponentEventFilter::NodeResized`) for
/// `node_id` whose layout box went from `old` to `new`.
///
/// `None` when its SIZE did not change: a position-only move is not a
/// resize, and a NaN dimension present on both sides reads as unchanged (see
/// `size_changed`; a raw `!=` once produced a Resize every frame forever).
///
/// This is the constructor the layout tail uses after EVERY solve (full
/// rebuild, pre-cascade relayout, window-resize fast path). The older
/// reconcile-time emitter compared layout maps that production always
/// passed EMPTY, so `NodeResized` had never fired in a running app.
#[must_use]
pub fn resize_event_for_bounds(
    dom_id: DomId,
    node_id: NodeId,
    old: LogicalRect,
    new: LogicalRect,
    timestamp: &Instant,
) -> Option<SyntheticEvent> {
    if !size_changed(old.size, new.size) {
        return None;
    }
    Some(create_lifecycle_event(
        EventType::Resize,
        node_id,
        dom_id,
        timestamp,
        LifecycleEventData {
            reason: LifecycleReason::Resize,
            previous_bounds: Some(old),
            current_bounds: new,
        },
    ))
}

/// Result of lifecycle event detection with reconciliation.
///
/// Contains both the generated lifecycle events and a mapping from old to new
/// node IDs for state migration (focus, scroll, etc.).
#[derive(Debug, Clone, Default)]
pub struct LifecycleEventResult {
    /// Lifecycle events (Mount, Unmount, Resize, Update)
    pub events: Vec<SyntheticEvent>,
    /// Maps old `NodeId` -> new `NodeId` for matched nodes.
    /// Use this to migrate focus, scroll state, and other node-specific state.
    pub node_id_mapping: OrderedMap<NodeId, NodeId>,
}

/// Detect lifecycle events using reconciliation with stable keys and content hashing.
///
/// This is the advanced lifecycle detection that can correctly identify:
/// - **Moves**: When a node changes position but keeps its identity (via key or hash)
/// - **Mounts**: When a new node appears
/// - **Unmounts**: When an existing node disappears
/// - **Resizes**: When a node's layout bounds change
/// - **Updates**: When a keyed node's content changes
///
/// The reconciliation strategy is:
/// 1. **Stable Key Match:** Nodes with `.with_reconciliation_key()` are matched by key (O(1))
/// 2. **Hash Match:** Nodes without keys are matched by content hash (enables reorder detection)
/// 3. **Fallback:** Unmatched nodes generate Mount/Unmount events
///
/// # Arguments
/// * `dom_id` - The DOM identifier
/// * `old_node_data` - Node data from the previous frame
/// * `new_node_data` - Node data from the current frame
/// * `old_layout` - Layout bounds from the previous frame
/// * `new_layout` - Layout bounds from the current frame
/// * `timestamp` - Current timestamp for events
///
/// # Returns
/// A `LifecycleEventResult` containing:
/// - `events`: Lifecycle events to dispatch
/// - `node_id_mapping`: Mapping from old to new `NodeIds` for state migration
///
/// # Example
/// ```rust,ignore
/// let result = detect_lifecycle_events_with_reconciliation(
///     dom_id,
///     &old_node_data,
///     &new_node_data,
///     &old_layout,
///     &new_layout,
///     timestamp,
/// );
///
/// // Dispatch lifecycle events
/// for event in result.events {
///     dispatch_event(event);
/// }
///
/// // Migrate focus to new node ID
/// if let Some(focused) = focus_manager.focused_node {
///     if let Some(&new_id) = result.node_id_mapping.get(&focused) {
///         focus_manager.focused_node = Some(new_id);
///     } else {
///         // Focused node was unmounted
///         focus_manager.focused_node = None;
///     }
/// }
/// ```
#[must_use]
pub fn detect_lifecycle_events_with_reconciliation(
    dom_id: DomId,
    old_node_data: &[crate::dom::NodeData],
    new_node_data: &[crate::dom::NodeData],
    old_hierarchy: &[crate::styled_dom::NodeHierarchyItem],
    new_hierarchy: &[crate::styled_dom::NodeHierarchyItem],
    old_layout: &OrderedMap<NodeId, LogicalRect>,
    new_layout: &OrderedMap<NodeId, LogicalRect>,
    timestamp: Instant,
) -> LifecycleEventResult {
    let diff_result = crate::diff::reconcile_dom(
        old_node_data,
        new_node_data,
        old_hierarchy,
        new_hierarchy,
        old_layout,
        new_layout,
        dom_id,
        timestamp,
    );

    LifecycleEventResult {
        events: diff_result.events,
        node_id_mapping: crate::diff::create_migration_map(&diff_result.node_moves),
    }
}

/// Event filter that only fires when an element is hovered over.
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[repr(C)]
pub enum HoverEventFilter {
    /// Mouse moved over the hovered element
    MouseOver,
    /// Any mouse button pressed on the hovered element
    MouseDown,
    /// Left mouse button pressed on the hovered element
    LeftMouseDown,
    /// Right mouse button pressed on the hovered element
    RightMouseDown,
    /// Middle mouse button pressed on the hovered element
    MiddleMouseDown,
    /// A completed ACTIVATION on this element: press and release on the same
    /// node, per W3C `click`. This - not `MouseUp` - is what "the user
    /// activated this control" means, and it is what Enter/Space on a focused
    /// element and an assistive technology's default action also dispatch.
    /// `MouseUp` stays the raw pointer-release event.
    Click,
    /// Any mouse button released on the hovered element
    MouseUp,
    /// Left mouse button released on the hovered element
    LeftMouseUp,
    /// Right mouse button released on the hovered element
    RightMouseUp,
    /// Middle mouse button released on the hovered element
    MiddleMouseUp,
    /// Mouse entered the hovered element bounds
    MouseEnter,
    /// Mouse left the hovered element bounds
    MouseLeave,
    /// Scroll event on the hovered element
    Scroll,
    /// Scroll started on the hovered element
    ScrollStart,
    /// Scroll ended on the hovered element
    ScrollEnd,
    /// Text input received while element is hovered
    TextInput,
    /// Virtual key pressed while element is hovered
    VirtualKeyDown,
    /// Virtual key released while element is hovered
    VirtualKeyUp,
    /// File is being hovered over the element
    HoveredFile,
    /// File was dropped onto the element
    DroppedFile,
    /// File hover was cancelled
    HoveredFileCancelled,
    /// Touch started on the hovered element
    TouchStart,
    /// Touch moved on the hovered element
    TouchMove,
    /// Touch ended on the hovered element
    TouchEnd,
    /// Touch was cancelled on the hovered element
    TouchCancel,
    /// Pen/stylus made contact on the hovered element
    PenDown,
    /// Pen/stylus moved while in contact on the hovered element
    PenMove,
    /// Pen/stylus lifted from the hovered element
    PenUp,
    /// Pen/stylus entered proximity of the hovered element
    PenEnter,
    /// Pen/stylus left proximity of the hovered element
    PenLeave,
    /// Apple Pencil 2 / Surface Slim Pen 2 barrel squeeze on the hovered
    /// element. Fires once per squeeze. The matching W3C primitive is the
    /// `PointerEvent` with `pointerType: "pen"` and a transient
    /// `tangentialPressure` spike — most apps tie a tool-switch to it.
    PenSqueeze,
    /// Apple Pencil 2 side double-tap on the hovered element. Fires once
    /// per gesture. Usually mapped to "undo" or "switch eraser".
    PenDoubleTap,
    /// Pen/stylus is hovering above the hovered element (in proximity,
    /// not in contact). Continuous: fires per pen-axis update while the
    /// stylus is held above the surface. Maps to W3C
    /// `PointerEvent('pointermove')` with `buttons: 0` and
    /// `pointerType: 'pen'`.
    PenHover,
    /// New GPS / network location fix arrived for a `GeolocationProbe`
    /// in this node's subtree. Payload accessor:
    /// `CallbackInfo::get_geolocation_fix()`.
    GeolocationFix,
    /// Native geolocation subscription errored / was revoked /
    /// timed out.
    GeolocationError,
    /// A motion-sensor reading changed (P6). Window-level mirror:
    /// `WindowEventFilter::SensorChanged`. Read via `get_sensor_reading`.
    SensorChanged,
    /// A gamepad's state changed / it (dis)connected (P6). Read via
    /// `get_primary_gamepad` / `get_gamepad_state`.
    GamepadInput,
    /// Drag started on the hovered element
    DragStart,
    /// Drag in progress on the hovered element
    Drag,
    /// Drag ended on the hovered element
    DragEnd,
    /// Dragged element entered this element (drop target)
    DragEnter,
    /// Dragged element is over this element (drop target, fires continuously)
    DragOver,
    /// Dragged element left this element (drop target)
    DragLeave,
    /// Element was dropped on this element (drop target)
    Drop,
    /// Double-click detected on the hovered element
    DoubleClick,
    /// Long press detected on the hovered element
    LongPress,
    /// Swipe left gesture on the hovered element
    SwipeLeft,
    /// Swipe right gesture on the hovered element
    SwipeRight,
    /// Swipe up gesture on the hovered element
    SwipeUp,
    /// Swipe down gesture on the hovered element
    SwipeDown,
    /// Pinch-in (zoom out) gesture on the hovered element
    PinchIn,
    /// Pinch-out (zoom in) gesture on the hovered element
    PinchOut,
    /// Clockwise rotation gesture on the hovered element
    RotateClockwise,
    /// Counter-clockwise rotation gesture on the hovered element
    RotateCounterClockwise,

    // W3C MouseOut event (bubbling version of MouseLeave)
    /// Mouse left the element OR moved to a child element (W3C `mouseout`, bubbles)
    MouseOut,

    // W3C Focus events (bubbling versions)
    /// Focus is about to move INTO this element or a descendant (W3C `focusin`, bubbles)
    FocusIn,
    /// Focus is about to move OUT of this element or a descendant (W3C `focusout`, bubbles)
    FocusOut,

    // IME Composition events
    /// IME composition started (W3C `compositionstart`)
    CompositionStart,
    /// IME composition updated (W3C `compositionupdate`)
    CompositionUpdate,
    /// IME composition ended (W3C `compositionend`)
    CompositionEnd,

    // Internal System Events (not exposed to user callbacks)
    #[doc(hidden)]
    /// Internal: Single click for text cursor placement
    SystemTextSingleClick,
    #[doc(hidden)]
    /// Internal: Double click for word selection
    SystemTextDoubleClick,
    #[doc(hidden)]
    /// Internal: Triple click for paragraph/line selection
    SystemTextTripleClick,

    // Async capability outcomes (MWA-A1b)
    /// A permission's OS-observed state changed while this node (the
    /// capability's most recent subscriber) is in the target chain.
    PermissionChanged,
    /// A biometric authentication prompt completed.
    BiometricResult,
    /// The screen eyedropper finished (picked or cancelled).
    ScreenColorPicked,
    /// A keyring store / get / delete operation completed.
    KeyringResult,
    /// The thumb "back" button was pressed. APPENDED at the end for ABI
    /// stability.
    ///
    /// Every shell already routes this button — Win32 `WM_XBUTTONDOWN`, macOS
    /// `otherMouseDown:`, X11 button 8 — into `MouseButton::Other(3)`, and it
    /// died there because no filter named it. Nearly every mouse sold in a
    /// decade has the pair, and browsers, IDEs and file managers all bind them
    /// to navigate back/forward.
    BackMouseDown,
    /// The thumb "back" button was released.
    BackMouseUp,
    /// The thumb "forward" button was pressed.
    ForwardMouseDown,
    /// The thumb "forward" button was released.
    ForwardMouseUp,
    /// A form was submitted — Enter on a focused control, or a submit
    /// button activated. APPENDED at the end for ABI stability.
    Submit,
    /// A control's value was COMMITTED, which is not the same as edited.
    /// APPENDED at the end.
    ///
    /// `TextInput` fires on every keystroke; this fires once, when the value
    /// settles — on blur, or on Enter. A field that validates on `TextInput`
    /// scolds the user halfway through typing an email address; one that
    /// validates on `Change` waits until they have finished.
    Change,
    /// A form was reset to its initial values. APPENDED at the end.
    Reset,
    /// A control failed validation. APPENDED at the end.
    Invalid,
    /// A dial turned over this node. APPENDED at the end.
    DialRotate,
    /// A dial was clicked over this node. APPENDED at the end.
    DialClick,
    /// The pointer moved while over this node. APPENDED at the end.
    MouseMove,
}

impl HoverEventFilter {
    /// Check if this is an internal system event that should not be exposed to user callbacks
    #[must_use]
    pub const fn is_system_internal(&self) -> bool {
        matches!(
            self,
            Self::SystemTextSingleClick | Self::SystemTextDoubleClick | Self::SystemTextTripleClick
        )
    }

    // Exhaustive On -> Option<FocusEventFilter> mapping table; the several `=> None`
    // rows (window-only events) are intentional 1:1 rows — merging would collapse the table.
    #[allow(clippy::match_same_arms)]
    #[must_use]
    pub const fn to_focus_event_filter(&self) -> Option<FocusEventFilter> {
        match self {
            // No focus mirror: a dial is delivered by POSITION (hover) or to
            // the window, never by focus.
            Self::DialRotate | Self::DialClick => None,
            Self::MouseOver => Some(FocusEventFilter::MouseOver),
            Self::MouseMove => Some(FocusEventFilter::MouseMove),
            Self::MouseDown => Some(FocusEventFilter::MouseDown),
            Self::LeftMouseDown => Some(FocusEventFilter::LeftMouseDown),
            Self::RightMouseDown => Some(FocusEventFilter::RightMouseDown),
            Self::MiddleMouseDown => Some(FocusEventFilter::MiddleMouseDown),
            // Activation is HOVER-scoped: it targets the node that was
            // activated, and dispatch already walks that node's ancestors, so
            // there is no separate focus-scoped spelling to map onto.
            Self::Click => None,
            Self::MouseUp => Some(FocusEventFilter::MouseUp),
            Self::LeftMouseUp => Some(FocusEventFilter::LeftMouseUp),
            Self::RightMouseUp => Some(FocusEventFilter::RightMouseUp),
            Self::MiddleMouseUp => Some(FocusEventFilter::MiddleMouseUp),
            Self::MouseEnter => Some(FocusEventFilter::MouseEnter),
            Self::MouseLeave => Some(FocusEventFilter::MouseLeave),
            Self::Scroll => Some(FocusEventFilter::Scroll),
            Self::ScrollStart => Some(FocusEventFilter::ScrollStart),
            Self::ScrollEnd => Some(FocusEventFilter::ScrollEnd),
            Self::TextInput => Some(FocusEventFilter::TextInput),
            Self::VirtualKeyDown => Some(FocusEventFilter::VirtualKeyDown),
            Self::VirtualKeyUp => Some(FocusEventFilter::VirtualKeyUp),
            Self::HoveredFile => None,
            Self::DroppedFile => None,
            Self::HoveredFileCancelled => None,
            Self::TouchStart => None,
            Self::TouchMove => None,
            Self::TouchEnd => None,
            Self::TouchCancel => None,
            Self::PenDown => Some(FocusEventFilter::PenDown),
            Self::PenMove => Some(FocusEventFilter::PenMove),
            Self::PenUp => Some(FocusEventFilter::PenUp),
            Self::PenEnter => None,
            Self::PenLeave => None,
            Self::PenSqueeze => None,
            Self::PenDoubleTap => None,
            Self::PenHover => None,
            Self::GeolocationFix => None,
            Self::GeolocationError => None,
            Self::SensorChanged => None,
            Self::GamepadInput => None,
            Self::DragStart => Some(FocusEventFilter::DragStart),
            Self::Drag => Some(FocusEventFilter::Drag),
            Self::DragEnd => Some(FocusEventFilter::DragEnd),
            Self::DragEnter => Some(FocusEventFilter::DragEnter),
            Self::DragOver => Some(FocusEventFilter::DragOver),
            Self::DragLeave => Some(FocusEventFilter::DragLeave),
            Self::Drop => Some(FocusEventFilter::Drop),
            Self::DoubleClick => Some(FocusEventFilter::DoubleClick),
            Self::LongPress => Some(FocusEventFilter::LongPress),
            Self::SwipeLeft => Some(FocusEventFilter::SwipeLeft),
            Self::SwipeRight => Some(FocusEventFilter::SwipeRight),
            Self::SwipeUp => Some(FocusEventFilter::SwipeUp),
            Self::SwipeDown => Some(FocusEventFilter::SwipeDown),
            Self::PinchIn => Some(FocusEventFilter::PinchIn),
            Self::PinchOut => Some(FocusEventFilter::PinchOut),
            Self::RotateClockwise => Some(FocusEventFilter::RotateClockwise),
            Self::RotateCounterClockwise => Some(FocusEventFilter::RotateCounterClockwise),
            Self::MouseOut => Some(FocusEventFilter::MouseLeave), // mouseout → closest focus equivalent
            Self::FocusIn => Some(FocusEventFilter::FocusIn),
            Self::FocusOut => Some(FocusEventFilter::FocusOut),
            Self::CompositionStart => Some(FocusEventFilter::CompositionStart),
            Self::CompositionUpdate => Some(FocusEventFilter::CompositionUpdate),
            Self::CompositionEnd => Some(FocusEventFilter::CompositionEnd),
            // System internal events - don't convert to focus events
            Self::SystemTextSingleClick => None,
            Self::SystemTextDoubleClick => None,
            Self::SystemTextTripleClick => None,
            // Async capability outcomes — no focus-filter equivalents
            Self::PermissionChanged => None,
            Self::BiometricResult => None,
            Self::ScreenColorPicked => None,
            Self::KeyringResult => None,
            // Thumb buttons have a Focus twin; the rest of the additions do
            // not (a HID report and a modifier change belong to the window).
            Self::BackMouseDown => Some(FocusEventFilter::BackMouseDown),
            Self::BackMouseUp => Some(FocusEventFilter::BackMouseUp),
            Self::ForwardMouseDown => Some(FocusEventFilter::ForwardMouseDown),
            Self::ForwardMouseUp => Some(FocusEventFilter::ForwardMouseUp),
            // Form events have a Focus twin: they belong to the control that
            // was being edited, not to whatever is hovered.
            Self::Submit => Some(FocusEventFilter::Submit),
            Self::Change => Some(FocusEventFilter::Change),
            Self::Reset => Some(FocusEventFilter::Reset),
            Self::Invalid => Some(FocusEventFilter::Invalid),
        }
    }
}

/// Event filter similar to `HoverEventFilter` that only fires when the element is focused.
///
/// **Important**: In order for this to fire, the item must have a `tabindex` attribute
/// (to indicate that the item is focus-able).
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[repr(C)]
pub enum FocusEventFilter {
    /// Mouse moved over the focused element
    MouseOver,
    /// Any mouse button pressed on the focused element
    MouseDown,
    /// Left mouse button pressed on the focused element
    LeftMouseDown,
    /// Right mouse button pressed on the focused element
    RightMouseDown,
    /// Middle mouse button pressed on the focused element
    MiddleMouseDown,
    /// Any mouse button released on the focused element
    MouseUp,
    /// Left mouse button released on the focused element
    LeftMouseUp,
    /// Right mouse button released on the focused element
    RightMouseUp,
    /// Middle mouse button released on the focused element
    MiddleMouseUp,
    /// Mouse entered the focused element bounds
    MouseEnter,
    /// Mouse left the focused element bounds
    MouseLeave,
    /// Scroll event on the focused element
    Scroll,
    /// Scroll started on the focused element
    ScrollStart,
    /// Scroll ended on the focused element
    ScrollEnd,
    /// Text input received while element is focused
    TextInput,
    /// Virtual key pressed while element is focused
    VirtualKeyDown,
    /// Virtual key released while element is focused
    VirtualKeyUp,
    /// Element received keyboard focus
    FocusReceived,
    /// Element lost keyboard focus
    FocusLost,
    /// Pen/stylus made contact on the focused element
    PenDown,
    /// Pen/stylus moved while in contact on the focused element
    PenMove,
    /// Pen/stylus lifted from the focused element
    PenUp,
    /// Drag started on the focused element
    DragStart,
    /// Drag in progress on the focused element
    Drag,
    /// Drag ended on the focused element
    DragEnd,
    /// Dragged element entered this focused element (drop target)
    DragEnter,
    /// Dragged element is over this focused element (drop target)
    DragOver,
    /// Dragged element left this focused element (drop target)
    DragLeave,
    /// Element was dropped on this focused element (drop target)
    Drop,
    /// Double-click detected on the focused element
    DoubleClick,
    /// Long press detected on the focused element
    LongPress,
    /// Swipe left gesture on the focused element
    SwipeLeft,
    /// Swipe right gesture on the focused element
    SwipeRight,
    /// Swipe up gesture on the focused element
    SwipeUp,
    /// Swipe down gesture on the focused element
    SwipeDown,
    /// Pinch-in (zoom out) gesture on the focused element
    PinchIn,
    /// Pinch-out (zoom in) gesture on the focused element
    PinchOut,
    /// Clockwise rotation gesture on the focused element
    RotateClockwise,
    /// Counter-clockwise rotation gesture on the focused element
    RotateCounterClockwise,

    // W3C Focus events (bubbling versions, fires on focused element when focus changes)
    /// Focus moved into this element or a descendant (W3C `focusin`)
    FocusIn,
    /// Focus moved out of this element or a descendant (W3C `focusout`)
    FocusOut,

    // IME Composition events
    /// IME composition started (W3C `compositionstart`)
    CompositionStart,
    /// IME composition updated (W3C `compositionupdate`)
    CompositionUpdate,
    /// IME composition ended (W3C `compositionend`)
    CompositionEnd,

    // Clipboard events (W3C clipboard-events; MWA-C-clipboard: fire on the
    // focused element BEFORE the OS default action, which preventDefault
    // suppresses). APPENDED at the end for ABI stability — sync to api.json
    // via azul-doc autofix in Phase D.
    /// Content is about to be copied from the focused element (W3C `copy`)
    Copy,
    /// Content is about to be cut from the focused element (W3C `cut`)
    Cut,
    /// Content is about to be pasted into the focused element (W3C `paste`)
    Paste,
    /// A structural document edit was recorded on (or under) the focused
    /// element and awaits the app's apply-and-ack (see
    /// `EventType::DocumentEdit`). APPENDED at the end for ABI stability.
    DocumentEdit,
    /// The focused editable's text was committed (see
    /// `EventType::TextChanged`): the post-commit counterpart of `TextInput`,
    /// which fires before the pending insertion is applied. APPENDED at the
    /// end for ABI stability.
    TextChanged,
    /// The thumb "back" button was pressed. APPENDED at the end for ABI
    /// stability.
    ///
    /// Every shell already routes this button — Win32 `WM_XBUTTONDOWN`, macOS
    /// `otherMouseDown:`, X11 button 8 — into `MouseButton::Other(3)`, and it
    /// died there because no filter named it. Nearly every mouse sold in a
    /// decade has the pair, and browsers, IDEs and file managers all bind them
    /// to navigate back/forward.
    BackMouseDown,
    /// The thumb "back" button was released.
    BackMouseUp,
    /// The thumb "forward" button was pressed.
    ForwardMouseDown,
    /// The thumb "forward" button was released.
    ForwardMouseUp,
    /// A form was submitted — Enter on a focused control, or a submit
    /// button activated. APPENDED at the end for ABI stability.
    Submit,
    /// A control's value was COMMITTED, which is not the same as edited.
    /// APPENDED at the end.
    ///
    /// `TextInput` fires on every keystroke; this fires once, when the value
    /// settles — on blur, or on Enter. A field that validates on `TextInput`
    /// scolds the user halfway through typing an email address; one that
    /// validates on `Change` waits until they have finished.
    Change,
    /// A form was reset to its initial values. APPENDED at the end.
    Reset,
    /// A control failed validation. APPENDED at the end.
    Invalid,
    /// The pointer moved while this node had focus. APPENDED at the end.
    MouseMove,
}

/// Event filter that fires when any action fires on the entire window
/// (regardless of whether any element is hovered or focused over).
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[repr(C)]
pub enum WindowEventFilter {
    /// Mouse moved anywhere in window
    MouseOver,
    /// Any mouse button pressed anywhere in window
    MouseDown,
    /// Left mouse button pressed anywhere in window
    LeftMouseDown,
    /// Right mouse button pressed anywhere in window
    RightMouseDown,
    /// Middle mouse button pressed anywhere in window
    MiddleMouseDown,
    /// Any mouse button released anywhere in window
    MouseUp,
    /// Left mouse button released anywhere in window
    LeftMouseUp,
    /// Right mouse button released anywhere in window
    RightMouseUp,
    /// Middle mouse button released anywhere in window
    MiddleMouseUp,
    /// Mouse entered the window
    MouseEnter,
    /// Mouse left the window
    MouseLeave,
    /// Scroll event anywhere in window
    Scroll,
    /// Scroll started anywhere in window
    ScrollStart,
    /// Scroll ended anywhere in window
    ScrollEnd,
    /// Text input received in window
    TextInput,
    /// Virtual key pressed in window
    VirtualKeyDown,
    /// Virtual key released in window
    VirtualKeyUp,
    /// File is being hovered over the window
    HoveredFile,
    /// File was dropped onto the window
    DroppedFile,
    /// File hover was cancelled
    HoveredFileCancelled,
    /// Window was resized
    Resized,
    /// Window was moved
    Moved,
    /// Window was minimized, maximized, restored, or toggled fullscreen
    FrameChanged,
    /// Touch started anywhere in window
    TouchStart,
    /// Touch moved anywhere in window
    TouchMove,
    /// Touch ended anywhere in window
    TouchEnd,
    /// Touch was cancelled
    TouchCancel,
    /// Window received focus
    FocusReceived,
    /// Window lost focus
    FocusLost,
    /// Window close was requested
    CloseRequested,
    /// System theme changed (light/dark mode)
    ThemeChanged,
    /// Window received OS-level focus
    WindowFocusReceived,
    /// Window lost OS-level focus
    WindowFocusLost,
    /// Pen/stylus made contact anywhere in window
    PenDown,
    /// Pen/stylus moved while in contact anywhere in window
    PenMove,
    /// Pen/stylus lifted anywhere in window
    PenUp,
    /// Pen/stylus entered window proximity
    PenEnter,
    /// Pen/stylus left window proximity
    PenLeave,
    /// Pen barrel-squeeze gesture fired in the window. See
    /// [`HoverEventFilter::PenSqueeze`].
    PenSqueeze,
    /// Pen side double-tap gesture fired in the window. See
    /// [`HoverEventFilter::PenDoubleTap`].
    PenDoubleTap,
    /// Pen hover in the window (in proximity, not in contact). See
    /// [`HoverEventFilter::PenHover`].
    PenHover,
    /// New GPS / network location fix arrived. Payload accessor:
    /// `CallbackInfo::get_geolocation_fix()`. Window-level rather
    /// than per-node because the user's location isn't bound to any
    /// particular DOM node — but a node-level mirror
    /// (`HoverEventFilter::GeolocationFix`) fires on every
    /// `GeolocationProbe` in the tree as well, for the common
    /// "redraw this node when the location changes" pattern.
    GeolocationFix,
    /// Native geolocation subscription dropped or errored (signal
    /// lost, no provider, permission revoked mid-session).
    GeolocationError,
    /// A motion-sensor reading changed (P6). Fires window-level (the device
    /// isn't bound to a node); read via `CallbackInfo::get_sensor_reading`.
    SensorChanged,
    /// A gamepad's buttons / axes changed or it (dis)connected (P6); read via
    /// `get_primary_gamepad` / `get_gamepad_state`.
    GamepadInput,
    /// Drag started anywhere in window
    DragStart,
    /// Drag in progress anywhere in window
    Drag,
    /// Drag ended anywhere in window
    DragEnd,
    /// Dragged element entered a drop target in window
    DragEnter,
    /// Dragged element is over a drop target in window
    DragOver,
    /// Dragged element left a drop target in window
    DragLeave,
    /// Element was dropped on a drop target in window
    Drop,
    /// Double-click detected anywhere in window
    DoubleClick,
    /// Long press detected anywhere in window
    LongPress,
    /// Swipe left gesture anywhere in window
    SwipeLeft,
    /// Swipe right gesture anywhere in window
    SwipeRight,
    /// Swipe up gesture anywhere in window
    SwipeUp,
    /// Swipe down gesture anywhere in window
    SwipeDown,
    /// Pinch-in (zoom out) gesture anywhere in window
    PinchIn,
    /// Pinch-out (zoom in) gesture anywhere in window
    PinchOut,
    /// Clockwise rotation gesture anywhere in window
    RotateClockwise,
    /// Counter-clockwise rotation gesture anywhere in window
    RotateCounterClockwise,
    /// The window's DPI scale factor changed (e.g., moved to a monitor with
    /// different scaling). The new DPI is available via `CallbackInfo::get_hidpi_factor()`.
    DpiChanged,
    /// The window moved to a different monitor. The new monitor is available
    /// via `CallbackInfo::get_current_monitor()`.
    MonitorChanged,

    // Async capability outcomes (MWA-A1b) — window-level mirrors (the
    // outcome isn't inherently bound to a node).
    /// A permission's OS-observed state changed.
    PermissionChanged,
    /// A biometric authentication prompt completed.
    BiometricResult,
    /// The screen eyedropper finished (picked or cancelled).
    ScreenColorPicked,
    /// A keyring store / get / delete operation completed.
    KeyringResult,
    /// The thumb "back" button was pressed. APPENDED at the end for ABI
    /// stability.
    ///
    /// Every shell already routes this button — Win32 `WM_XBUTTONDOWN`, macOS
    /// `otherMouseDown:`, X11 button 8 — into `MouseButton::Other(3)`, and it
    /// died there because no filter named it. Nearly every mouse sold in a
    /// decade has the pair, and browsers, IDEs and file managers all bind them
    /// to navigate back/forward.
    BackMouseDown,
    /// The thumb "back" button was released.
    BackMouseUp,
    /// The thumb "forward" button was pressed.
    ForwardMouseDown,
    /// The thumb "forward" button was released.
    ForwardMouseUp,
    /// Raw, pre-acceleration pointer motion. APPENDED at the end for ABI
    /// stability.
    ///
    /// Window-scoped rather than hover-scoped because raw motion has no
    /// position: there is no node under it to hit-test, and a locked pointer
    /// is a window-wide mode.
    RawMouseMotion,
    /// A modifier or lock key changed state. APPENDED at the end.
    ModifiersChanged,
    /// A HID device delivered an input report. APPENDED at the end.
    ///
    /// Window-scoped like `RawMouseMotion`: a HID report has no position, so
    /// there is no node it belongs to.
    HidReport,
    /// A dial turned. APPENDED at the end.
    ///
    /// Window-scoped as well as node-scoped: a dial used OFF the screen (every
    /// device except a Surface Dial on a Surface Studio) reports no contact
    /// point, so no node is under it and only the window can receive it.
    DialRotate,
    /// A dial with a physical click was pressed. APPENDED at the end.
    DialClick,
    /// The pointer moved anywhere in the window. APPENDED at the end.
    MouseMove,
    /// The pointer lock was taken, released, or ended by the platform
    /// (9d-ii-c). Window-level: the lock belongs to the window, not a node.
    PointerLockChange,
    /// Media playback started (11c). APPENDED at the end for ABI stability.
    ///
    /// The window mirror of [`ExternalEventFilter::Play`]. Media state is
    /// reported by an EXTERNAL player, not by a device the window hit-tests,
    /// so `External` is its home; this pair exists because a media event
    /// belongs to the window in exactly the sense a monitor being unplugged
    /// does, and an app that already listens window-wide should not have to
    /// learn a second family to hear it.
    Play,
    /// Media playback paused. APPENDED at the end.
    Pause,
    /// Media playback reached the end. APPENDED at the end.
    Ended,
    /// The media position advanced (throttled — see
    /// `managers::media_player::TIME_UPDATE_INTERVAL_S`). APPENDED at the end.
    TimeUpdate,
    /// The media volume or mute state changed. APPENDED at the end.
    VolumeChange,
    /// The media pipeline failed. APPENDED at the end.
    MediaError,
}

impl WindowEventFilter {
    // Exhaustive On -> Option<HoverEventFilter> mapping table (see to_focus_event_filter).
    #[allow(clippy::match_same_arms)]
    #[must_use]
    pub const fn to_hover_event_filter(&self) -> Option<HoverEventFilter> {
        match self {
            Self::DialRotate => Some(HoverEventFilter::DialRotate),
            Self::DialClick => Some(HoverEventFilter::DialClick),
            Self::MouseOver => Some(HoverEventFilter::MouseOver),
            Self::MouseMove => Some(HoverEventFilter::MouseMove),
            Self::MouseDown => Some(HoverEventFilter::MouseDown),
            Self::LeftMouseDown => Some(HoverEventFilter::LeftMouseDown),
            Self::RightMouseDown => Some(HoverEventFilter::RightMouseDown),
            Self::MiddleMouseDown => Some(HoverEventFilter::MiddleMouseDown),
            Self::MouseUp => Some(HoverEventFilter::MouseUp),
            Self::LeftMouseUp => Some(HoverEventFilter::LeftMouseUp),
            Self::RightMouseUp => Some(HoverEventFilter::RightMouseUp),
            Self::MiddleMouseUp => Some(HoverEventFilter::MiddleMouseUp),
            Self::Scroll => Some(HoverEventFilter::Scroll),
            Self::ScrollStart => Some(HoverEventFilter::ScrollStart),
            Self::ScrollEnd => Some(HoverEventFilter::ScrollEnd),
            Self::TextInput => Some(HoverEventFilter::TextInput),
            Self::VirtualKeyDown => Some(HoverEventFilter::VirtualKeyDown),
            Self::VirtualKeyUp => Some(HoverEventFilter::VirtualKeyUp),
            Self::HoveredFile => Some(HoverEventFilter::HoveredFile),
            Self::DroppedFile => Some(HoverEventFilter::DroppedFile),
            Self::HoveredFileCancelled => Some(HoverEventFilter::HoveredFileCancelled),
            // MouseEnter and MouseLeave on the **window** - does not mean a mouseenter
            // and a mouseleave on the hovered element
            Self::MouseEnter => None,
            Self::MouseLeave => None,
            Self::Resized => None,
            Self::Moved => None,
            // A frame transition is a WINDOW fact; there is no per-element
            // hover equivalent to map it onto.
            Self::FrameChanged => None,
            Self::TouchStart => Some(HoverEventFilter::TouchStart),
            Self::TouchMove => Some(HoverEventFilter::TouchMove),
            Self::TouchEnd => Some(HoverEventFilter::TouchEnd),
            Self::TouchCancel => Some(HoverEventFilter::TouchCancel),
            Self::FocusReceived => None,
            Self::FocusLost => None,
            Self::CloseRequested => None,
            Self::ThemeChanged => None,
            Self::WindowFocusReceived => None, // specific to window!
            Self::WindowFocusLost => None,     // specific to window!
            Self::PointerLockChange => None,   // specific to window!
            Self::PenDown => Some(HoverEventFilter::PenDown),
            Self::PenMove => Some(HoverEventFilter::PenMove),
            Self::PenUp => Some(HoverEventFilter::PenUp),
            Self::PenEnter => Some(HoverEventFilter::PenEnter),
            Self::PenLeave => Some(HoverEventFilter::PenLeave),
            Self::PenSqueeze => Some(HoverEventFilter::PenSqueeze),
            Self::PenDoubleTap => Some(HoverEventFilter::PenDoubleTap),
            Self::PenHover => Some(HoverEventFilter::PenHover),
            Self::GeolocationFix => Some(HoverEventFilter::GeolocationFix),
            Self::GeolocationError => Some(HoverEventFilter::GeolocationError),
            Self::SensorChanged => Some(HoverEventFilter::SensorChanged),
            Self::GamepadInput => Some(HoverEventFilter::GamepadInput),
            Self::DragStart => Some(HoverEventFilter::DragStart),
            Self::Drag => Some(HoverEventFilter::Drag),
            Self::DragEnd => Some(HoverEventFilter::DragEnd),
            Self::DragEnter => Some(HoverEventFilter::DragEnter),
            Self::DragOver => Some(HoverEventFilter::DragOver),
            Self::DragLeave => Some(HoverEventFilter::DragLeave),
            Self::Drop => Some(HoverEventFilter::Drop),
            Self::DoubleClick => Some(HoverEventFilter::DoubleClick),
            Self::LongPress => Some(HoverEventFilter::LongPress),
            Self::SwipeLeft => Some(HoverEventFilter::SwipeLeft),
            Self::SwipeRight => Some(HoverEventFilter::SwipeRight),
            Self::SwipeUp => Some(HoverEventFilter::SwipeUp),
            Self::SwipeDown => Some(HoverEventFilter::SwipeDown),
            Self::PinchIn => Some(HoverEventFilter::PinchIn),
            Self::PinchOut => Some(HoverEventFilter::PinchOut),
            Self::RotateClockwise => Some(HoverEventFilter::RotateClockwise),
            Self::RotateCounterClockwise => Some(HoverEventFilter::RotateCounterClockwise),
            // Window-specific events with no hover equivalent
            Self::DpiChanged => None,
            Self::MonitorChanged => None,
            // Async capability outcomes — mirror to the hover twin
            Self::PermissionChanged => Some(HoverEventFilter::PermissionChanged),
            Self::BiometricResult => Some(HoverEventFilter::BiometricResult),
            Self::ScreenColorPicked => Some(HoverEventFilter::ScreenColorPicked),
            Self::KeyringResult => Some(HoverEventFilter::KeyringResult),
            Self::BackMouseDown => Some(HoverEventFilter::BackMouseDown),
            Self::BackMouseUp => Some(HoverEventFilter::BackMouseUp),
            Self::ForwardMouseDown => Some(HoverEventFilter::ForwardMouseDown),
            Self::ForwardMouseUp => Some(HoverEventFilter::ForwardMouseUp),
            // Window-only: no position to hit-test, so no hover twin.
            Self::RawMouseMotion | Self::ModifiersChanged | Self::HidReport => None,
            // Media state (11c) has no hover twin either: it is reported by an
            // external player, and there is no pointer position that could
            // decide which node it "happened over".
            Self::Play
            | Self::Pause
            | Self::Ended
            | Self::TimeUpdate
            | Self::VolumeChange
            | Self::MediaError => None,
        }
    }
}

/// Defines events related to the lifecycle of a DOM node itself.
#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[repr(C)]
pub enum ComponentEventFilter {
    /// Fired after the component is first mounted into the DOM.
    AfterMount,
    /// Fired just before the component is removed from the DOM.
    BeforeUnmount,
    /// Fired when the node's layout rectangle has been resized.
    NodeResized,
    /// Fired to trigger the default action for an accessibility component.
    DefaultAction,
    /// Fired when the component becomes selected.
    Selected,
    /// Fired when a keyed component's content has changed (props/state update).
    Updated,
    /// Fired on a `<transient-window>` the user dismissed (outside click or
    /// Escape). The popup is closed by the engine regardless; this is where
    /// the app clears its own `open` state so the next layout agrees.
    Dismissed,
    /// Fired on a `<transient-window>` the user tore off its anchor by
    /// dragging its `-azul-app-region: drag` strip; it is a free toplevel
    /// now. The event's `current_bounds` is its rect in the parent.
    TornOff,
    /// Fired on a torn-off `<transient-window>` the user docked back - onto
    /// its anchor, or onto a `tearoff-zone` node, which is its anchor from
    /// here on.
    Docked,
}

/// Defines application-level events not tied to a specific window or node.
#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[repr(C)]
pub enum ApplicationEventFilter {
    /// Fired when a new hardware device is connected.
    DeviceConnected,
    /// Fired when a hardware device is disconnected.
    DeviceDisconnected,
    /// Fired when a new monitor/display is connected to the system.
    /// Callback receives updated monitor list via `CallbackInfo::get_monitors()`.
    MonitorConnected,
    /// Fired when a monitor/display is disconnected from the system.
    MonitorDisconnected,
    /// The platform's media controls asked for a seek (9h-i-a-i-a). APPENDED
    /// at the end for ABI stability.
    MediaControl,
    /// The system changed the app's hold on the audio (9h-i-a-i-d-i).
    SystemAudioChange,
}

/// Events reported by something OUTSIDE the input pipeline (11c).
///
/// The other four families answer "where did this land?" — hovered, focused,
/// window-wide, on this component. A media player answers none of those: the
/// state change happens in an external player (a decoder thread, a platform
/// media service, the app's own transport calls) and is then reported IN. It
/// is the same shape as a monitor being unplugged, one level closer to the
/// app.
///
/// Dispatched like a window filter: every node carrying a matching callback
/// is invoked, and the event's `target` names the media node so a callback
/// serving several players can tell them apart.
#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[repr(C)]
pub enum ExternalEventFilter {
    /// Media playback started.
    Play,
    /// Media playback paused.
    Pause,
    /// Media playback reached the end of its known duration. Fires exactly
    /// once per arrival at the end (reaching it also stops the transport).
    Ended,
    /// The media position advanced. THROTTLED to one event per 250 ms of
    /// media time (`managers::media_player::TIME_UPDATE_INTERVAL_S`) — the
    /// web's ~4/s budget — because a playing video would otherwise raise one
    /// per frame for its entire length.
    TimeUpdate,
    /// The media volume or mute state changed.
    VolumeChange,
    /// The media pipeline reported a failure; the transport is stopped.
    MediaError,
}

/// Sets the target for what events can reach the callbacks specifically.
///
/// This determines the condition under which an event is fired, such as whether
/// the node is hovered, focused, or if the event is window-global.
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[repr(C, u8)]
pub enum EventFilter {
    /// Calls the attached callback when the mouse is actively over the
    /// given element.
    Hover(HoverEventFilter),
    /// Calls the attached callback when the element is currently focused.
    Focus(FocusEventFilter),
    /// Calls the callback when anything related to the window is happening.
    /// The "hit item" will be the root item of the DOM.
    /// For example, this can be useful for tracking the mouse position
    /// (in relation to the window). In difference to `Desktop`, this only
    /// fires when the window is focused.
    ///
    /// This can also be good for capturing controller input, touch input
    /// (i.e. global gestures that aren't attached to any component, but rather
    /// the "window" itself).
    Window(WindowEventFilter),
    /// API stub: Something happened with the node itself (node resized, created or removed).
    Component(ComponentEventFilter),
    /// Something happened with the application (started, shutdown, device plugged in).
    Application(ApplicationEventFilter),
    /// Something was reported by an external source that the hit test cannot
    /// place — media playback state, today. APPENDED at the end for ABI
    /// stability (`EventFilter` is `repr(C, u8)`; a variant inserted anywhere
    /// but the tail would renumber every discriminant after it).
    External(ExternalEventFilter),
}

impl EventFilter {
    #[must_use]
    pub const fn is_focus_callback(&self) -> bool {
        matches!(self, Self::Focus(_))
    }
    #[must_use]
    pub const fn is_window_callback(&self) -> bool {
        matches!(self, Self::Window(_))
    }
}

/// Creates a function inside an impl <enum type> block that returns a single
/// variant if the enum is that variant.
macro_rules! get_single_enum_type {
    ($fn_name:ident, $enum_name:ident:: $variant:ident($return_type:ty)) => {
        #[must_use]
        pub const fn $fn_name(&self) -> Option<$return_type> {
            use self::$enum_name::*;
            match self {
                $variant(e) => Some(*e),
                _ => None,
            }
        }
    };
}

impl EventFilter {
    get_single_enum_type!(as_hover_event_filter, EventFilter::Hover(HoverEventFilter));
    get_single_enum_type!(as_focus_event_filter, EventFilter::Focus(FocusEventFilter));
    get_single_enum_type!(
        as_window_event_filter,
        EventFilter::Window(WindowEventFilter)
    );
}

/// Convert from `On` enum to `EventFilter`.
///
/// This determines which specific filter variant is used based on the event type.
/// For example, `On::TextInput` becomes a Focus event filter, while `On::VirtualKeyDown`
/// becomes a Window event filter (since it's global to the window).
impl From<On> for EventFilter {
    // Exhaustive On -> EventFilter mapping table; the a11y events (Default/Collapse/
    // Expand/Increment/Decrement) all map to MouseUp ("click") as intentional 1:1
    // documented rows — merging would drop the per-row rationale comments.
    #[allow(clippy::match_same_arms)]
    fn from(input: On) -> Self {
        use crate::dom::On::{
            Collapse, Decrement, Default, DroppedFile, Expand, FocusLost, FocusReceived,
            HoveredFile, HoveredFileCancelled, Increment, LeftMouseDown, LeftMouseUp,
            MiddleMouseDown, MiddleMouseUp, MouseDown, MouseEnter, MouseLeave, MouseMove,
            MouseOver, MouseUp, RightMouseDown, RightMouseUp, Scroll, TextInput, VirtualKeyDown,
            VirtualKeyUp,
        };
        match input {
            MouseOver => Self::Hover(HoverEventFilter::MouseOver),
            MouseMove => Self::Hover(HoverEventFilter::MouseMove),
            MouseDown => Self::Hover(HoverEventFilter::MouseDown),
            LeftMouseDown => Self::Hover(HoverEventFilter::LeftMouseDown),
            MiddleMouseDown => Self::Hover(HoverEventFilter::MiddleMouseDown),
            RightMouseDown => Self::Hover(HoverEventFilter::RightMouseDown),
            On::Click => Self::Hover(HoverEventFilter::Click),
            MouseUp => Self::Hover(HoverEventFilter::MouseUp),
            LeftMouseUp => Self::Hover(HoverEventFilter::LeftMouseUp),
            MiddleMouseUp => Self::Hover(HoverEventFilter::MiddleMouseUp),
            RightMouseUp => Self::Hover(HoverEventFilter::RightMouseUp),

            MouseEnter => Self::Hover(HoverEventFilter::MouseEnter),
            MouseLeave => Self::Hover(HoverEventFilter::MouseLeave),
            Scroll => Self::Hover(HoverEventFilter::Scroll),
            TextInput => Self::Focus(FocusEventFilter::TextInput), // focus!
            On::DocumentEdit => Self::Focus(FocusEventFilter::DocumentEdit), // focus!
            On::TextChanged => Self::Focus(FocusEventFilter::TextChanged), // focus!
            VirtualKeyDown => Self::Window(WindowEventFilter::VirtualKeyDown), // window!
            VirtualKeyUp => Self::Window(WindowEventFilter::VirtualKeyUp), // window!
            HoveredFile => Self::Hover(HoverEventFilter::HoveredFile),
            DroppedFile => Self::Hover(HoverEventFilter::DroppedFile),
            HoveredFileCancelled => Self::Hover(HoverEventFilter::HoveredFileCancelled),
            FocusReceived => Self::Focus(FocusEventFilter::FocusReceived), // focus!
            FocusLost => Self::Focus(FocusEventFilter::FocusLost),         // focus!

            // Accessibility events are ACTIVATIONS, so they map to `Click` -
            // the same filter a pointer click and a keyboard Enter/Space
            // reach. They used to map to `MouseUp`, which conflated
            // activation with a raw pointer release.
            Default => Self::Hover(HoverEventFilter::Click),
            Collapse => Self::Hover(HoverEventFilter::Click),
            Expand => Self::Hover(HoverEventFilter::Click),
            Increment => Self::Hover(HoverEventFilter::Click),
            Decrement => Self::Hover(HoverEventFilter::Click),
        }
    }
}

// Cross-Platform Event Dispatch System
// NOTE: The old dispatch_synthetic_events / CallbackTarget / CallbackToInvoke / EventDispatchResult
// pipeline has been removed. Event dispatch now goes through dispatch_events_propagated() in
// event_v2.rs which uses propagate_event() for W3C Capture→Target→Bubble propagation.

/// Trait for managers to provide their pending events.
///
/// Each manager (`TextInputManager`, `ScrollManager`, etc.) implements this to
/// report what events occurred since the last frame. This enables a unified,
/// lazy event determination system.
pub trait EventProvider {
    /// Get all pending events from this manager.
    ///
    /// Events should include:
    ///
    /// - `target`: The `DomNodeId` that was affected
    /// - `event_type`: What happened (Input, Scroll, Focus, etc.)
    /// - `source`: `EventSource::User` for input, `EventSource::Programmatic` for API calls
    /// - `data`: Type-specific event data
    ///
    /// After calling this, the manager should mark events as "read" so they
    /// aren't returned again next frame.
    fn get_pending_events(&self, timestamp: Instant) -> Vec<SyntheticEvent>;
}

/// Deduplicate synthetic events by (target node, event type).
///
/// Groups by (target.dom, target.node, `event_type`), keeping the latest timestamp.
#[must_use]
pub fn deduplicate_synthetic_events(mut events: Vec<SyntheticEvent>) -> Vec<SyntheticEvent> {
    if events.len() <= 1 {
        return events;
    }

    // The pointer SEAT is part of the key (9b-ii-b): two cursors pressing the
    // same node are two presses, not one. Non-pointer events key on the
    // primary and coalesce exactly as before.
    let seat_of = |e: &SyntheticEvent| match &e.data {
        EventData::Mouse(m) => m.seat_id,
        EventData::Scroll(s) => s.seat_id,
        EventData::Touch(t) => t.seat_id,
        EventData::Composition(c) => c.seat_id,
        _ => crate::window::PRIMARY_POINTER_SEAT,
    };
    events.sort_by_key(|e| (e.target.dom, e.target.node, e.event_type, seat_of(e)));

    // Coalesce consecutive events with same target, event_type and seat
    let mut result = Vec::with_capacity(events.len());
    let mut iter = events.into_iter();

    if let Some(mut prev) = iter.next() {
        for curr in iter {
            if prev.target == curr.target
                && prev.event_type == curr.event_type
                && seat_of(&prev) == seat_of(&curr)
            {
                // Keep the one with later timestamp
                prev = if curr.timestamp > prev.timestamp {
                    curr
                } else {
                    prev
                };
            } else {
                result.push(prev);
                prev = curr;
            }
        }
        result.push(prev);
    }

    result
}

/// Every `HoverEventFilter` variant, so planning can be derived from matching.
static ALL_HOVER: &[HoverEventFilter] = &[
    HoverEventFilter::MouseOver,
    HoverEventFilter::MouseMove,
    HoverEventFilter::MouseDown,
    HoverEventFilter::LeftMouseDown,
    HoverEventFilter::RightMouseDown,
    HoverEventFilter::MiddleMouseDown,
    HoverEventFilter::Click,
    HoverEventFilter::MouseUp,
    HoverEventFilter::LeftMouseUp,
    HoverEventFilter::RightMouseUp,
    HoverEventFilter::MiddleMouseUp,
    HoverEventFilter::MouseEnter,
    HoverEventFilter::MouseLeave,
    HoverEventFilter::Scroll,
    HoverEventFilter::ScrollStart,
    HoverEventFilter::ScrollEnd,
    HoverEventFilter::TextInput,
    HoverEventFilter::VirtualKeyDown,
    HoverEventFilter::VirtualKeyUp,
    HoverEventFilter::HoveredFile,
    HoverEventFilter::DroppedFile,
    HoverEventFilter::HoveredFileCancelled,
    HoverEventFilter::TouchStart,
    HoverEventFilter::TouchMove,
    HoverEventFilter::TouchEnd,
    HoverEventFilter::TouchCancel,
    HoverEventFilter::PenDown,
    HoverEventFilter::PenMove,
    HoverEventFilter::PenUp,
    HoverEventFilter::PenEnter,
    HoverEventFilter::PenLeave,
    HoverEventFilter::PenSqueeze,
    HoverEventFilter::PenDoubleTap,
    HoverEventFilter::PenHover,
    HoverEventFilter::GeolocationFix,
    HoverEventFilter::GeolocationError,
    HoverEventFilter::SensorChanged,
    HoverEventFilter::GamepadInput,
    HoverEventFilter::DragStart,
    HoverEventFilter::Drag,
    HoverEventFilter::DragEnd,
    HoverEventFilter::DragEnter,
    HoverEventFilter::DragOver,
    HoverEventFilter::DragLeave,
    HoverEventFilter::Drop,
    HoverEventFilter::DoubleClick,
    HoverEventFilter::LongPress,
    HoverEventFilter::SwipeLeft,
    HoverEventFilter::SwipeRight,
    HoverEventFilter::SwipeUp,
    HoverEventFilter::SwipeDown,
    HoverEventFilter::PinchIn,
    HoverEventFilter::PinchOut,
    HoverEventFilter::RotateClockwise,
    HoverEventFilter::RotateCounterClockwise,
    HoverEventFilter::MouseOut,
    HoverEventFilter::FocusIn,
    HoverEventFilter::FocusOut,
    HoverEventFilter::CompositionStart,
    HoverEventFilter::CompositionUpdate,
    HoverEventFilter::CompositionEnd,
    HoverEventFilter::SystemTextSingleClick,
    HoverEventFilter::SystemTextDoubleClick,
    HoverEventFilter::SystemTextTripleClick,
    HoverEventFilter::PermissionChanged,
    HoverEventFilter::BiometricResult,
    HoverEventFilter::ScreenColorPicked,
    HoverEventFilter::KeyringResult,
    // Form events. These have matcher arms and planning arms, but were absent
    // from THIS list — and planning is DERIVED by probing it, so a filter the
    // list does not name can never be planned and dispatches to nothing. Same
    // dead-filter shape the arc exists to close, reintroduced by the arc.
    HoverEventFilter::Submit,
    HoverEventFilter::Change,
    HoverEventFilter::Reset,
    HoverEventFilter::Invalid,
    // Planning is DERIVED by probing this list, so a filter missing from it
    // can never be planned — the failure this arc has hit repeatedly.
    HoverEventFilter::DialRotate,
    HoverEventFilter::DialClick,
];

/// Every `FocusEventFilter` variant, so planning can be derived from matching.
static ALL_FOCUS: &[FocusEventFilter] = &[
    FocusEventFilter::MouseOver,
    FocusEventFilter::MouseMove,
    FocusEventFilter::MouseDown,
    FocusEventFilter::LeftMouseDown,
    FocusEventFilter::RightMouseDown,
    FocusEventFilter::MiddleMouseDown,
    FocusEventFilter::MouseUp,
    FocusEventFilter::LeftMouseUp,
    FocusEventFilter::RightMouseUp,
    FocusEventFilter::MiddleMouseUp,
    FocusEventFilter::MouseEnter,
    FocusEventFilter::MouseLeave,
    FocusEventFilter::Scroll,
    FocusEventFilter::ScrollStart,
    FocusEventFilter::ScrollEnd,
    FocusEventFilter::TextInput,
    FocusEventFilter::VirtualKeyDown,
    FocusEventFilter::VirtualKeyUp,
    FocusEventFilter::FocusReceived,
    FocusEventFilter::FocusLost,
    FocusEventFilter::PenDown,
    FocusEventFilter::PenMove,
    FocusEventFilter::PenUp,
    FocusEventFilter::DragStart,
    FocusEventFilter::Drag,
    FocusEventFilter::DragEnd,
    FocusEventFilter::DragEnter,
    FocusEventFilter::DragOver,
    FocusEventFilter::DragLeave,
    FocusEventFilter::Drop,
    FocusEventFilter::DoubleClick,
    FocusEventFilter::LongPress,
    FocusEventFilter::SwipeLeft,
    FocusEventFilter::SwipeRight,
    FocusEventFilter::SwipeUp,
    FocusEventFilter::SwipeDown,
    FocusEventFilter::PinchIn,
    FocusEventFilter::PinchOut,
    FocusEventFilter::RotateClockwise,
    FocusEventFilter::RotateCounterClockwise,
    FocusEventFilter::FocusIn,
    FocusEventFilter::FocusOut,
    FocusEventFilter::CompositionStart,
    FocusEventFilter::CompositionUpdate,
    FocusEventFilter::CompositionEnd,
    FocusEventFilter::Copy,
    FocusEventFilter::Cut,
    FocusEventFilter::Paste,
    FocusEventFilter::DocumentEdit,
    FocusEventFilter::TextChanged,
    // Form events. These have matcher arms and planning arms, but were absent
    // from THIS list — and planning is DERIVED by probing it, so a filter the
    // list does not name can never be planned and dispatches to nothing. Same
    // dead-filter shape the arc exists to close, reintroduced by the arc.
    FocusEventFilter::Submit,
    FocusEventFilter::Change,
    FocusEventFilter::Reset,
    FocusEventFilter::Invalid,
];

/// Every `WindowEventFilter` variant, so planning can be derived from matching.
static ALL_WINDOW: &[WindowEventFilter] = &[
    WindowEventFilter::MouseOver,
    WindowEventFilter::MouseMove,
    WindowEventFilter::MouseDown,
    WindowEventFilter::LeftMouseDown,
    WindowEventFilter::RightMouseDown,
    WindowEventFilter::MiddleMouseDown,
    WindowEventFilter::MouseUp,
    WindowEventFilter::LeftMouseUp,
    WindowEventFilter::RightMouseUp,
    WindowEventFilter::MiddleMouseUp,
    WindowEventFilter::MouseEnter,
    WindowEventFilter::MouseLeave,
    WindowEventFilter::Scroll,
    WindowEventFilter::ScrollStart,
    WindowEventFilter::ScrollEnd,
    WindowEventFilter::TextInput,
    WindowEventFilter::VirtualKeyDown,
    WindowEventFilter::VirtualKeyUp,
    WindowEventFilter::HoveredFile,
    WindowEventFilter::DroppedFile,
    WindowEventFilter::HoveredFileCancelled,
    WindowEventFilter::Resized,
    WindowEventFilter::Moved,
    WindowEventFilter::FrameChanged,
    WindowEventFilter::TouchStart,
    WindowEventFilter::TouchMove,
    WindowEventFilter::TouchEnd,
    WindowEventFilter::TouchCancel,
    WindowEventFilter::FocusReceived,
    WindowEventFilter::FocusLost,
    WindowEventFilter::CloseRequested,
    WindowEventFilter::ThemeChanged,
    WindowEventFilter::WindowFocusReceived,
    WindowEventFilter::WindowFocusLost,
    WindowEventFilter::PointerLockChange,
    WindowEventFilter::PenDown,
    WindowEventFilter::PenMove,
    WindowEventFilter::PenUp,
    WindowEventFilter::PenEnter,
    WindowEventFilter::PenLeave,
    WindowEventFilter::PenSqueeze,
    WindowEventFilter::PenDoubleTap,
    WindowEventFilter::PenHover,
    WindowEventFilter::GeolocationFix,
    WindowEventFilter::GeolocationError,
    WindowEventFilter::SensorChanged,
    WindowEventFilter::GamepadInput,
    WindowEventFilter::DragStart,
    WindowEventFilter::Drag,
    WindowEventFilter::DragEnd,
    WindowEventFilter::DragEnter,
    WindowEventFilter::DragOver,
    WindowEventFilter::DragLeave,
    WindowEventFilter::Drop,
    WindowEventFilter::DoubleClick,
    WindowEventFilter::LongPress,
    WindowEventFilter::SwipeLeft,
    WindowEventFilter::SwipeRight,
    WindowEventFilter::SwipeUp,
    WindowEventFilter::SwipeDown,
    WindowEventFilter::PinchIn,
    WindowEventFilter::PinchOut,
    WindowEventFilter::RotateClockwise,
    WindowEventFilter::RotateCounterClockwise,
    WindowEventFilter::DpiChanged,
    WindowEventFilter::MonitorChanged,
    WindowEventFilter::PermissionChanged,
    WindowEventFilter::BiometricResult,
    WindowEventFilter::ScreenColorPicked,
    WindowEventFilter::KeyringResult,
    WindowEventFilter::DialRotate,
    WindowEventFilter::DialClick,
    // Media (11c). Planning is DERIVED by probing this list, so a filter the
    // list does not name can never be planned, whatever its matcher says.
    WindowEventFilter::Play,
    WindowEventFilter::Pause,
    WindowEventFilter::Ended,
    WindowEventFilter::TimeUpdate,
    WindowEventFilter::VolumeChange,
    WindowEventFilter::MediaError,
];

/// Every `ComponentEventFilter` variant, so planning can be derived from
/// matching. This is the family the derivation FORGOT when it replaced the
/// hand-written table: with no component probe, `Mount` planned zero filters
/// and every `AfterMount` / `Updated` / `NodeResized` / `Dismissed` /
/// `TornOff` / `Docked` callback in the engine went silent — the reconcile
/// diff kept emitting the events, the dispatcher's `Component` arm simply
/// never saw one (`headless_lifecycle` caught it: mount=0 on the first frame).
/// `DefaultAction` and `Selected` have no event type, so probing them is a
/// no-op today; they are listed so the table stays the whole enum.
static ALL_COMPONENT: &[ComponentEventFilter] = &[
    ComponentEventFilter::AfterMount,
    ComponentEventFilter::BeforeUnmount,
    ComponentEventFilter::NodeResized,
    ComponentEventFilter::DefaultAction,
    ComponentEventFilter::Selected,
    ComponentEventFilter::Updated,
    ComponentEventFilter::Dismissed,
    ComponentEventFilter::TornOff,
    ComponentEventFilter::Docked,
];


/// Every `ExternalEventFilter`, for planning to probe. See [`ALL_COMPONENT`].
static ALL_EXTERNAL: &[ExternalEventFilter] = &[
    ExternalEventFilter::Play,
    ExternalEventFilter::Pause,
    ExternalEventFilter::Ended,
    ExternalEventFilter::TimeUpdate,
    ExternalEventFilter::VolumeChange,
    ExternalEventFilter::MediaError,
];

/// Every `ApplicationEventFilter`, for planning to probe. See [`ALL_COMPONENT`].
static ALL_APPLICATION: &[ApplicationEventFilter] = &[
    ApplicationEventFilter::DeviceConnected,
    ApplicationEventFilter::DeviceDisconnected,
    ApplicationEventFilter::MonitorConnected,
    ApplicationEventFilter::MonitorDisconnected,
    ApplicationEventFilter::MediaControl,
    ApplicationEventFilter::SystemAudioChange,
];

/// Which listeners an event should reach.
///
/// DERIVED from `matches_filter_phase`, the phase-matching table, so the two
/// can no longer disagree. They used to be two hand-written tables that had
/// to be kept in step by discipline, and an exhaustive cross-product found 61
/// pairs where they had drifted - in BOTH directions. A filter the matcher
/// accepts but planning never emitted produced a listener that could never
/// fire (pen enter/leave, scroll start/end, every focus-scoped drag event);
/// a filter planned but not matched collected a callback and dropped it. The
/// visible symptoms were Enter/Space activating nothing and, briefly, a
/// pointer click activating a control TWICE.
///
/// Dispatch sites use this to decide which callbacks to COLLECT and then ask
/// the matcher again per callback, so "collected" and "fired" now answer to
/// one table.
///
/// The universe is the four `ALL_*` tables - Hover, Focus, Window, Component
/// - and it has to be ALL of them: a family missing from the probe is a whole
/// class of listeners that can never fire, and nothing else in the pipeline
/// notices (the events are still produced, the callbacks still registered).
/// That is how every lifecycle callback went dead when the derivation first
/// shipped without `ALL_COMPONENT`; the cross-product test
/// `planning_and_matching_agree_for_every_event_and_filter` now covers all
/// four families so that the next omission fails there.
///
/// Cost: one pass over the filter universe per EVENT (not per node, not per
/// callback) - a few hundred `match` arms, nanoseconds, and it happens once
/// where the old table was also built once.
#[must_use]
pub fn event_type_to_filters(event_type: EventType, event_data: &EventData) -> Vec<EventFilter> {
    // Built through the public constructor so a new field on `SyntheticEvent`
    // cannot silently change what planning probes with.
    let probe = SyntheticEvent::new(
        event_type,
        EventSource::User,
        DomNodeId {
            dom: DomId::ROOT_ID,
            node: crate::styled_dom::NodeHierarchyItemId::from_crate_internal(Some(NodeId::new(0))),
        },
        crate::task::Instant::Tick(crate::task::SystemTick::new(0)),
        event_data.clone(),
    );

    let mut out = Vec::new();
    for f in ALL_HOVER {
        if matches_filter_phase(EventFilter::Hover(*f), &probe, EventPhase::Bubble) {
            out.push(EventFilter::Hover(*f));
        }
    }
    for f in ALL_FOCUS {
        if matches_filter_phase(EventFilter::Focus(*f), &probe, EventPhase::Bubble) {
            out.push(EventFilter::Focus(*f));
        }
    }
    for f in ALL_WINDOW {
        if matches_filter_phase(EventFilter::Window(*f), &probe, EventPhase::Bubble) {
            out.push(EventFilter::Window(*f));
        }
    }
    // Component and Application were simply not probed here. Their matcher
    // arms (`matches_component_filter` / `matches_application_filter`) were
    // correct — but planning never asked them anything, so NO lifecycle or
    // application event could ever be planned, and every
    // `EventFilter::Component(..)` callback in every app was dead.
    for f in ALL_COMPONENT {
        if matches_filter_phase(EventFilter::Component(*f), &probe, EventPhase::Bubble) {
            out.push(EventFilter::Component(*f));
        }
    }
    for f in ALL_APPLICATION {
        if matches_filter_phase(EventFilter::Application(*f), &probe, EventPhase::Bubble) {
            out.push(EventFilter::Application(*f));
        }
    }
    for f in ALL_EXTERNAL {
        if matches_filter_phase(EventFilter::External(*f), &probe, EventPhase::Bubble) {
            out.push(EventFilter::External(*f));
        }
    }
    out
}

// Internal System Event Processing

/// Framework-determined side effects (system changes).
///
/// Unlike `CallbackChange` (from user callbacks), these are determined by the
/// framework's event analysis: hit tests, gesture detection, focus rules,
/// text selection, keyboard shortcuts, etc.
///
/// Both `CallbackChange` (user) and `SystemChange` (framework) are processed
/// through exhaustive match on `PlatformWindowV2` — adding a new variant
/// causes a compile error in `apply_system_change()`.
#[derive(Debug, Clone, PartialEq, Eq)]
#[must_use = "SystemChange must be processed through apply_system_change()"]
pub enum SystemChange {
    /// Advance layout animations by an EXACT step, bypassing the wall clock.
    ///
    /// Only the E2E surface emits this. A headless scenario cannot sample real
    /// time: the same test would land on a different point of the curve on a
    /// fast machine than a slow one, so any assertion mid-flight would be
    /// flaky. Stepping by a fixed `dt` makes the trajectory a pure function of
    /// how many times this ran.
    ///
    /// A `SystemChange` rather than a direct call because `CallbackInfo` hands
    /// out `&LayoutWindow` only — mutation is required to go through this
    /// channel, which is also where the mutable window actually exists.
    // === Text Selection ===

    /// Process a mouse click for text selection (single/double/triple click).
    TextSelectionClick {
        position: LogicalPosition,
        timestamp: Instant,
    },
    /// Extend text selection via mouse drag.
    TextSelectionDrag {
        start_position: LogicalPosition,
        current_position: LogicalPosition,
    },
    /// Unified selection operation: cursor movement, selection extension, or deletion.
    ///
    /// Replaces the old `ArrowKeyNavigation` and `DeleteTextSelection` variants.
    /// Every keyboard shortcut maps to a single `SelectionOp` — see its docs.
    ApplySelectionOp {
        target: DomNodeId,
        op: SelectionOp,
        /// The SEAT whose key this was (9b-ii-a-i-d-ii-b): the op acts on that
        /// seat's caret. Seat 0 is the primary.
        seat_id: u64,
    },

    // === Keyboard Shortcuts ===
    /// Copy selected text to system clipboard (Ctrl+C / Cmd+C).
    CopyToClipboard,
    /// Cut selected text to clipboard and delete (Ctrl+X / Cmd+X).
    CutToClipboard { target: DomNodeId },
    /// Paste text from system clipboard at cursor (Ctrl+V / Cmd+V).
    PasteFromClipboard,
    /// Select all text in focused node (Ctrl+A / Cmd+A).
    SelectAllText,
    /// Undo last text edit (Ctrl+Z / Cmd+Z).
    UndoTextEdit { target: DomNodeId },
    /// Redo last undone edit (Ctrl+Y / Ctrl+Shift+Z / Cmd+Shift+Z).
    RedoTextEdit { target: DomNodeId },

    // === Multi-Cursor ===
    /// Add a cursor at the clicked position (Ctrl+Click).
    /// The position will be hit-tested to find the text cursor location.
    AddCursorAtClick { position: LogicalPosition },
    /// Select the next occurrence of the current selection's text (Ctrl+D).
    /// If the primary selection is a cursor, expand it to the word first.
    SelectNextOccurrence { target: DomNodeId },
    /// A NON-primary seat's editing shortcut (9b-ii-a-i-d-ii-b-i): Copy /
    /// Cut / Paste / Select-all / Undo / Redo on THAT seat's focus and caret.
    /// The primary's shortcuts stay the dedicated variants above.
    SeatShortcut {
        seat_id: u64,
        target: DomNodeId,
        shortcut: KeyboardShortcut,
    },

    // === Text Input ===
    /// Apply pending text input from platform (keyboard/IME).
    ApplyPendingTextInput,
    /// Apply text changeset (incremental relayout).
    ApplyTextChangeset,

    // === Drag & Drop ===
    /// Activate node drag on a draggable element.
    ActivateNodeDrag { dom_id: DomId, node_id: NodeId },
    /// Activate window drag (CSD titlebar).
    ActivateWindowDrag,
    /// Set up drag visual state (:dragging pseudo-state, GPU transform key).
    InitDragVisualState,
    /// Set :drag-over pseudo-state on a target node.
    SetDragOverState { target: DomNodeId, active: bool },
    /// Update current drop target in drag context.
    UpdateDropTarget { target: DomNodeId },
    /// Update GPU transform for active node drag.
    UpdateDragGpuTransform,
    /// End drag: clear pseudo-states, remove GPU keys, end drag session.
    DeactivateDrag,

    // === Focus ===
    /// Move a NON-primary seat's focus (9b-ii-a-i-d): only that seat's
    /// entry changes - no `:focus` restyle, no caret / blink timer, no soft
    /// keyboard, which all follow the primary's focus (the text-edit session
    /// is one). A primary-seat change is `SetFocus`.
    SetSeatFocus {
        seat_id: u64,
        new_focus: Option<DomNodeId>,
        old_focus: Option<DomNodeId>,
    },
    /// Change focus to a new target (or clear focus if None).
    /// Handles: `set_focused_node`, `apply_focus_restyle`, `scroll_node_into_view`,
    /// `cursor_blink_timer` start/stop.
    SetFocus {
        new_focus: Option<DomNodeId>,
        old_focus: Option<DomNodeId>,
        /// Should this focus be INDICATED - the W3C `:focus-visible` question.
        ///
        /// It travels WITH the change because the handler restyles and
        /// regenerates the display list, and the focus ring is emitted by that
        /// regeneration. Setting the flag afterwards (which the shell used to
        /// do for the keyboard route) means the frame that was just built did
        /// not know focus was indicated, so the ring only appeared on whatever
        /// repaint happened NEXT - a click, a resize. On the device that read
        /// as "Tab does not ring anything until you click something", while the
        /// E2E harness - which happened to set the flag first - showed a ring
        /// and passed (device report, 2026-09-01).
        visible: bool,
    },
    /// Clear all text selections.
    ClearAllSelections,
    /// Finalize pending focus changes (cursor initialization after layout).
    FinalizePendingFocusChanges,

    // === Scroll ===
    /// Scroll cursor/selection into view.
    ScrollSelectionIntoView,
    /// Scroll a specific node into view.
    ScrollNodeIntoView { target: DomNodeId },
    /// Scroll cursor into view after text input (needs relayout first).
    ScrollCursorIntoViewAfterTextInput,

    // === Auto-Scroll Timer ===
    /// Start auto-scroll timer for drag-to-scroll (60Hz).
    StartAutoScrollTimer,
    /// Cancel auto-scroll timer.
    StopAutoScrollTimer,
}

impl_option!(
    SystemChange,
    OptionSystemChange,
    copy = false,
    clone = false,
    [Debug, Clone, PartialEq, Eq]
);

impl_vec!(
    SystemChange,
    SystemChangeVec,
    SystemChangeVecDestructor,
    SystemChangeVecDestructorType,
    SystemChangeVecSlice,
    OptionSystemChange
);
impl_vec_debug!(SystemChange, SystemChangeVec);
impl_vec_clone!(SystemChange, SystemChangeVec, SystemChangeVecDestructor);
impl_vec_partialeq!(SystemChange, SystemChangeVec);

/// Result of pre-callback internal event filtering
#[derive(Debug, Clone, PartialEq)]
pub struct PreCallbackFilterResult {
    /// System changes to process BEFORE user callbacks
    pub system_changes: Vec<SystemChange>,
    /// Regular events that will be passed to user callbacks
    pub user_events: Vec<SyntheticEvent>,
}

/// Flattened focus/selection state for the input interpreter (replaces trait objects).
#[derive(Debug, Clone, Copy)]
pub struct InputInterpreterState {
    pub focused_node: Option<DomNodeId>,
    pub click_count: u8,
    pub drag_start_position: Option<LogicalPosition>,
    pub has_selection: bool,
    /// Whether focus sits in a TEXT-EDITING context (a contenteditable host,
    /// a text input) - the only place arrow keys mean "move the caret".
    ///
    /// Without this the interpreter claimed every arrow key for a caret op
    /// and returned `AddAndSkip`, which SWALLOWS the event: it never reached
    /// user callbacks at all. A focused Slider or colour picker therefore
    /// could not implement arrow keys - the handler was never called (device
    /// report, 2026-09-01: "the arrow keys for sliders do not work at all,
    /// nor the four arrow keys for navigating the color gradient").
    pub focus_is_editable: bool,
}

/// All context needed by the input interpreter to map events to system changes.
///
/// Passed to the interpreter callback. Contains references to the current
/// events and window state. The interpreter reads this and returns system changes.
#[derive(Debug)]
pub struct InputInterpreterInfo<'a> {
    pub events: &'a [SyntheticEvent],
    pub hit_test: Option<&'a FullHitTest>,
    pub keyboard_state: &'a crate::window::KeyboardState,
    pub mouse_state: &'a crate::window::MouseState,
    pub state: InputInterpreterState,
    /// The focused node of each NON-primary keyboard seat present in
    /// `events` (9b-ii-a-i-d), from `seat_focus_of_events`; a seat missing
    /// here resolves to the primary's `state.focused_node`.
    pub seat_focus: &'a [(u64, Option<DomNodeId>)],
}

/// The `extern "C"` callback type for the input interpreter.
///
/// The first `RefAny` is the user data (vim mode, repeat counter, etc.)
/// held in `InputInterpreterCallback.ctx`. The `*const ()` is an opaque
/// pointer to `InputInterpreterInfo` — callers use the safe wrapper
/// methods to access event data. Returns a `PreCallbackFilterResult`.
///
/// For C/Python: the trampoline extracts the foreign callable from `RefAny.ctx`.
/// For Rust: use `InputInterpreterCallback::from(fn_ptr)` which sets ctx=None.
pub type InputInterpreterCallbackType = extern "C" fn(
    crate::refany::RefAny,
    *const InputInterpreterInfo<'static>, // Opaque; actual lifetime managed by caller
) -> PreCallbackFilterResult;

/// Configurable input interpreter callback.
///
/// Maps raw platform events + window state → semantic `SystemChange` actions.
/// The default (`default_input_interpreter`) handles standard desktop keybindings.
/// Replace this on `LayoutWindow` to implement vim, game controls, etc.
///
/// ## Pattern
/// - **Rust**: `InputInterpreterCallback::from(my_fn_ptr)` — `ctx` is None
/// - **Python/C**: Set `cb` to a trampoline, `ctx` to `RefAny` wrapping the foreign callable
#[repr(C)]
pub struct InputInterpreterCallback {
    pub cb: InputInterpreterCallbackType,
    pub ctx: crate::refany::OptionRefAny,
}

impl_callback!(InputInterpreterCallback, InputInterpreterCallbackType);

impl Default for InputInterpreterCallback {
    fn default() -> Self {
        Self {
            cb: default_input_interpreter_extern,
            ctx: crate::refany::OptionRefAny::None,
        }
    }
}

/// The `extern "C"` callback type for the post-callback filter.
pub type PostFilterCallbackType = extern "C" fn(
    crate::refany::RefAny,
    bool,                 // prevent_default
    SystemChangeVecSlice, // pre_changes (immutable slice)
    DomNodeId,            // old_focus (0xFFFF = None)
    DomNodeId,            // new_focus (0xFFFF = None)
) -> SystemChangeVec;

/// Configurable post-callback filter.
#[repr(C)]
pub struct PostFilterCallback {
    pub cb: PostFilterCallbackType,
    pub ctx: crate::refany::OptionRefAny,
}

impl_callback!(PostFilterCallback, PostFilterCallbackType);

impl Default for PostFilterCallback {
    fn default() -> Self {
        Self {
            cb: default_post_filter_extern,
            ctx: crate::refany::OptionRefAny::None,
        }
    }
}

/// What JSON type an op argument expects.
///
/// Spelled out rather than left to prose, because this is read by machines:
/// an agent choosing arguments and a UI validating a macro form both need the
/// type, not a sentence describing it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde-json", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde-json", serde(rename_all = "lowercase"))]
pub enum E2eOpArgType {
    String,
    Number,
    Bool,
    Object,
    Array,
    /// Any JSON value is acceptable.
    Any,
}

/// One argument of one op.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
#[cfg_attr(feature = "serde-json", derive(serde::Serialize, serde::Deserialize))]
pub struct E2eOpArg {
    pub name: String,
    #[cfg_attr(feature = "serde-json", serde(rename = "type"))]
    pub arg_type: E2eOpArgType,
    pub required: bool,
    pub description: String,
}

impl Default for E2eOpArgType {
    fn default() -> Self {
        Self::Any
    }
}

/// A worked example: what to send, and what comes back.
///
/// Both halves matter. The arguments alone tell a caller how to invoke the op;
/// the RETURN tells it what it can then assert on, which is what a scenario
/// author and an agent each need before committing to a call.
#[derive(Debug, Clone, PartialEq, Default)]
#[cfg_attr(feature = "serde-json", derive(serde::Serialize, serde::Deserialize))]
pub struct E2eOpExample {
    pub description: String,
    /// Example arguments — a real JSON value, not a string containing JSON.
    ///
    /// These were `String` first, which serialized as escaped JSON inside
    /// JSON: every consumer parsed twice and nothing checked the inner text
    /// was even well-formed, so a malformed example sat in the schema looking
    /// fine.
    pub args: crate::json::Json,
    /// What the op returns for those arguments.
    ///
    /// MUST contain a `success` boolean — validated when the schema is
    /// installed, see `E2eOpSchema::validate`.
    pub returns: crate::json::Json,
}

/// One op the application answers.
#[derive(Debug, Clone, PartialEq, Default)]
#[cfg_attr(feature = "serde-json", derive(serde::Serialize, serde::Deserialize))]
pub struct E2eOpDef {
    pub name: String,
    /// One line, for a list or a picker.
    pub summary: String,
    /// The long form, for a tooltip or an agent's context.
    pub description: String,
    pub args: Vec<E2eOpArg>,
    pub examples: Vec<E2eOpExample>,
}

/// Everything an application advertises about its ops.
///
/// Built in memory as a normal Rust struct and serialized to `Json` at the
/// boundary — on BOTH sides, framework and application. The `Json` hop is a
/// deliberate interim bridge so the shape can be iterated on without an ABI
/// break each time; these types get exposed through api.json later and the
/// bridge goes away.
#[derive(Debug, Clone, PartialEq, Default)]
#[cfg_attr(feature = "serde-json", derive(serde::Serialize, serde::Deserialize))]
pub struct E2eOpSchema {
    pub ops: Vec<E2eOpDef>,
}

/// Does this value have a top-level `success` boolean?
///
/// Deliberately requires a BOOLEAN, not merely the key: `"success": "yes"` and
/// `"success": null` are the shapes a hand-written schema actually produces,
/// and each would otherwise pass while telling a consumer nothing.
// Only the `not(serde-json)` arm is const-eligible (it is a literal `true`);
// the serde arm calls `to_serde_value`, which allocates. Marking the fn `const`
// would therefore stop compiling in the configuration that actually parses.
#[allow(clippy::missing_const_for_fn)]
fn json_has_success_bool(v: &crate::json::Json) -> bool {
    #[cfg(feature = "serde-json")]
    {
        v.to_serde_value()
            .get("success")
            .is_some_and(serde_json::Value::is_boolean)
    }
    #[cfg(not(feature = "serde-json"))]
    {
        // Without serde there is no parser here. Returning TRUE would silently
        // pass every schema; the honest fallback is a textual check that can
        // only reject things that are definitely wrong.
        let _ = v;
        true
    }
}

/// Why an advertised schema is unusable.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum E2eSchemaError {
    /// An op has no name.
    UnnamedOp { index: usize },
    /// Two ops share a name, so dispatch by name is ambiguous.
    DuplicateOpName { name: String },
    /// An argument has no name, or no usable type.
    UnnamedArg { op: String, index: usize },
    /// An example's `returns` has no `success` boolean.
    ///
    /// The contract is that every op result says whether it worked. An
    /// example that omits it is advertising a result shape the runtime is
    /// required to reject.
    ExampleMissingSuccess { op: String, index: usize },
}

impl core::fmt::Display for E2eSchemaError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            Self::UnnamedOp { index } => write!(f, "op #{index} has an empty name"),
            Self::DuplicateOpName { name } => {
                write!(
                    f,
                    "two ops are both named '{name}'; dispatch would be ambiguous"
                )
            }
            Self::UnnamedArg { op, index } => {
                write!(f, "op '{op}' argument #{index} has an empty name")
            }
            Self::ExampleMissingSuccess { op, index } => write!(
                f,
                "op '{op}' example #{index}: `returns` has no `success` boolean. Every op \
                 result must say whether it worked, or a failure is indistinguishable from a \
                 success"
            ),
        }
    }
}

impl E2eOpSchema {
    /// Check the schema is usable, BEFORE anything reads or dispatches it.
    ///
    /// Called when the schema is installed, not on first invocation. The whole
    /// point of advertising a schema is that a plugin, an MCP server or an
    /// agent reads it before calling anything — a schema that only proves
    /// malformed when an op is finally invoked has failed at its one job. An
    /// app shipping an unusable advertisement is a bug in the app, and its own
    /// startup is the cheapest place to catch it.
    ///
    /// # Errors
    ///
    /// Returns [`E2eSchemaError`] if the schema is malformed: a duplicate or
    /// empty op name, or an argument whose declared type is not a valid JSON
    /// type name.
    pub fn validate(&self) -> Result<(), E2eSchemaError> {
        let mut seen: Vec<&str> = Vec::new();
        for (i, op) in self.ops.iter().enumerate() {
            if op.name.trim().is_empty() {
                return Err(E2eSchemaError::UnnamedOp { index: i });
            }
            if seen.contains(&op.name.as_str()) {
                return Err(E2eSchemaError::DuplicateOpName {
                    name: op.name.clone(),
                });
            }
            seen.push(op.name.as_str());
            for (a, arg) in op.args.iter().enumerate() {
                if arg.name.trim().is_empty() {
                    return Err(E2eSchemaError::UnnamedArg {
                        op: op.name.clone(),
                        index: a,
                    });
                }
            }
            for (e, ex) in op.examples.iter().enumerate() {
                if !json_has_success_bool(&ex.returns) {
                    return Err(E2eSchemaError::ExampleMissingSuccess {
                        op: op.name.clone(),
                        index: e,
                    });
                }
            }
        }
        Ok(())
    }

    /// Serialize to the `Json` that crosses the C ABI.
    #[must_use]
    pub fn to_json(&self) -> crate::json::Json {
        #[cfg(feature = "serde-json")]
        {
            // Falling back to an empty-op object rather than to null: a
            // consumer must never be handed something that reads as "not
            // parseable" when the truth is "serialization failed".
            // serde_json preserves declaration order; `Json::parse` does NOT
            // (it re-serializes sorted, which buried `name` and `summary`
            // under `args`/`description`/`examples`). Keep the serialized text
            // and wrap it, rather than round-tripping through the parser.
            serde_json::to_string(self).ok().map_or_else(
                || crate::json::Json {
                    value_type: crate::json::JsonType::Object,
                    internal: crate::json::JsonInternal {
                        string_value: AzString::from_const_str(r#"{"ops":[]}"#),
                        ..Default::default()
                    },
                },
                |text| crate::json::Json {
                    value_type: crate::json::JsonType::Object,
                    internal: crate::json::JsonInternal {
                        string_value: AzString::from(text),
                        ..Default::default()
                    },
                },
            )
        }
        #[cfg(not(feature = "serde-json"))]
        crate::json::Json {
            value_type: crate::json::JsonType::Object,
            internal: crate::json::JsonInternal {
                string_value: AzString::from_const_str(r#"{"ops":[]}"#),
                ..Default::default()
            },
        }
    }
}

/// Outcome of a user-defined E2E op.
#[repr(C)]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CustomE2eOpResult {
    /// Whether the application RECOGNISED this op name.
    ///
    /// This is not "did it succeed" — it is "was this op mine at all". The
    /// debug server turns `false` into an explicit unknown-op error rather
    /// than an OK. Without it, a hook that returns a result for every name
    /// makes a typo'd op in a scenario indistinguishable from one that ran:
    /// non-assert ops produce no output of their own, so a silent success and
    /// a silent miss look identical from the outside.
    pub handled: bool,
    /// Result payload, JSON. Reported back to the scenario as-is, so a
    /// scenario can assert on it. Empty string is a valid empty result.
    pub json: AzString,
}

impl Default for CustomE2eOpResult {
    /// "Not my op": `handled: false` with an empty payload — the value a
    /// bridge (e.g. the generated Python trampoline) returns when no user
    /// handler can run. Mirrors the debug server's unknown-op semantics.
    fn default() -> Self {
        Self {
            handled: false,
            json: AzString::from_const_str(""),
        }
    }
}

/// The `extern "C"` callback type for a user-defined E2E op.
///
/// Receives the op name and its arguments as a JSON string, exactly as they
/// appeared in the scenario, and returns a `CustomE2eOpResult`. This is the
/// hook for driving application-level actions from a scenario — "now load the
/// document" — that the engine has no way to express on the app's behalf.
pub type CustomE2eOpCallbackType = extern "C" fn(
    crate::refany::RefAny, // ctx
    AzString,              // op name
    AzString,              // arguments, JSON
) -> CustomE2eOpResult;

/// Application-provided handler for E2E ops the engine does not implement.
#[repr(C)]
pub struct CustomE2eOpCallback {
    pub cb: CustomE2eOpCallbackType,
    pub ctx: crate::refany::OptionRefAny,
    /// Describes every op `cb` answers: name, summary, description, the JSON
    /// type each argument expects, usage examples, and example returns.
    ///
    /// DATA, not a second callback — discovery is a field read, so it needs
    /// no invocation and no debug HTTP server. That is what lets a plugin
    /// enumerate host capabilities, a locally-spawned MCP server expose the
    /// app to an agent that would otherwise drive it by screenshot, or a
    /// `script.json` be handed straight to the binary.
    ///
    /// The examples and types are not documentation garnish: they are what a
    /// macro picker renders and what an agent reads in place of a screenshot.
    ///
    /// `Json` deliberately, not typed structs — the schema can then follow an
    /// OpenAPI-style operation shape and gain fields without an ABI break.
    /// Typed structs come later.
    pub op_schema: crate::json::Json,
}

// `impl_callback_traits!` only ever reads `self.cb`, so it is correct here.
// The full `impl_callback!` is NOT usable: its generated `Clone` and `From`
// construct `Self { cb, ctx }` literally, and this struct has a third field.
impl_callback_traits!(CustomE2eOpCallback);

impl Clone for CustomE2eOpCallback {
    fn clone(&self) -> Self {
        Self {
            cb: self.cb,
            ctx: self.ctx.clone(),
            op_schema: self.op_schema.clone(),
        }
    }
}

impl From<CustomE2eOpCallbackType> for CustomE2eOpCallback {
    /// Installs a handler that advertises NOTHING.
    ///
    /// A bare fn pointer carries no schema, so this cannot invent one. An app
    /// converting from a fn pointer gets a working handler whose ops are
    /// undiscoverable until it sets `op_schema` — visible in a plugin listing
    /// as an empty op list, which is the honest answer rather than a guess.
    fn from(cb: CustomE2eOpCallbackType) -> Self {
        Self {
            cb,
            ..Self::default()
        }
    }
}

impl Default for CustomE2eOpCallback {
    fn default() -> Self {
        Self {
            cb: default_custom_e2e_op_extern,
            ctx: crate::refany::OptionRefAny::None,
            // An empty LIST, not an empty string or a null. A consumer must
            // be able to tell "this app advertises no ops" from "this app
            // returned nothing parseable"; those mean different things to a
            // plugin deciding whether the host is usable at all.
            // An empty LIST, not an empty string or a null. A consumer must
            // be able to tell "this app advertises no ops" from "this app
            // returned nothing parseable"; those mean different things to a
            // plugin deciding whether the host is usable at all.
            op_schema: E2eOpSchema::default().to_json(),
        }
    }
}

/// Default handler: recognises NOTHING.
///
/// `handled: false` is the load-bearing part. An app that has not installed a
/// handler must make a scenario referencing a custom op FAIL, not pass
/// quietly — the default has to be the safe answer, because it is the one
/// that ships when nobody thought about this.
#[must_use]
pub extern "C" fn default_custom_e2e_op_extern(
    _ctx: crate::refany::RefAny,
    _op: AzString,
    _args: AzString,
) -> CustomE2eOpResult {
    CustomE2eOpResult {
        handled: false,
        json: AzString::from_const_str(""),
    }
}

// Keep simpler Rust fn pointer aliases for internal use
pub type InputInterpreterFn = fn(info: &InputInterpreterInfo<'_>) -> PreCallbackFilterResult;

pub type PostFilterFn = fn(
    prevent_default: bool,
    pre_changes: &[SystemChange],
    old_focus: Option<DomNodeId>,
    new_focus: Option<DomNodeId>,
) -> Vec<SystemChange>;

/// Mouse button state for drag tracking
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct MouseButtonState {
    pub left_down: bool,
    pub right_down: bool,
    pub middle_down: bool,
}

/// Arrow key / cursor navigation directions
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ArrowDirection {
    Left,
    Right,
    Up,
    Down,
    /// Home key: move to start of current line
    LineStart,
    /// End key: move to end of current line
    LineEnd,
    /// Ctrl+Home: move to start of document
    DocumentStart,
    /// Ctrl+End: move to end of document
    DocumentEnd,
}

impl ArrowDirection {
    /// Map a `VirtualKeyCode` plus the `ctrl` modifier into an `ArrowDirection`.
    /// Returns `None` if the key is not a navigation key.
    #[must_use]
    pub const fn from_key(vk: crate::window::VirtualKeyCode, ctrl: bool) -> Option<Self> {
        use crate::window::VirtualKeyCode::{Down, End, Home, Left, Right, Up};
        Some(match vk {
            Left => Self::Left,
            Right => Self::Right,
            Up => Self::Up,
            Down => Self::Down,
            Home if ctrl => Self::DocumentStart,
            Home => Self::LineStart,
            End if ctrl => Self::DocumentEnd,
            End => Self::LineEnd,
            _ => return None,
        })
    }

    /// Convert to a `(SelectionDirection, SelectionStep)` pair for the
    /// selection-op interpreter. `ctrl` upgrades arrow keys to word jumps.
    #[must_use]
    pub const fn to_selection(self, ctrl: bool) -> (SelectionDirection, SelectionStep) {
        match self {
            Self::Left if ctrl => (SelectionDirection::Backward, SelectionStep::Word),
            Self::Right if ctrl => (SelectionDirection::Forward, SelectionStep::Word),
            Self::Left => (SelectionDirection::Backward, SelectionStep::Character),
            Self::Right => (SelectionDirection::Forward, SelectionStep::Character),
            Self::Up => (SelectionDirection::Backward, SelectionStep::VisualLine),
            Self::Down => (SelectionDirection::Forward, SelectionStep::VisualLine),
            Self::LineStart => (SelectionDirection::Backward, SelectionStep::Line),
            Self::LineEnd => (SelectionDirection::Forward, SelectionStep::Line),
            Self::DocumentStart => (SelectionDirection::Backward, SelectionStep::Document),
            Self::DocumentEnd => (SelectionDirection::Forward, SelectionStep::Document),
        }
    }
}

/// Direction of cursor movement or selection expansion.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(C)]
pub enum SelectionDirection {
    Forward,
    Backward,
}

/// Granularity of cursor movement or selection expansion.
///
/// Combined with `SelectionDirection`, determines how far a cursor moves
/// or a selection expands. Reused for navigation, deletion, and visual
/// selection — a single code path for word boundaries etc.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(C)]
pub enum SelectionStep {
    /// One grapheme cluster (arrow keys, Backspace, Delete)
    Character,
    /// One word boundary (Ctrl+arrow, Ctrl+Backspace, Ctrl+Delete)
    Word,
    /// To line boundary (Home/End)
    Line,
    /// One visual line up/down (Up/Down arrows)
    VisualLine,
    /// To document boundary (Ctrl+Home/End)
    Document,
}

/// What to do with the selection after moving.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(C)]
pub enum SelectionMode {
    /// Collapse selection to cursor, then move (plain arrow key).
    Move,
    /// Extend selection from anchor to new position (Shift+arrow).
    Extend,
    /// Expand cursor to range in the given direction, then delete the range
    /// (Backspace/Delete). If a range already exists, just delete it.
    Delete,
}

/// A unified selection operation that replaces all cursor movement,
/// selection extension, and text deletion commands.
///
/// Every keyboard shortcut for cursor movement or deletion maps to this:
/// - Arrow Left = (Backward, Character, Move, 1)
/// - Shift+Right = (Forward, Character, Extend, 1)
/// - Ctrl+Backspace = (Backward, Word, Delete, 1)
/// - Home = (Backward, Line, Move, 1)
/// - Ctrl+End = (Forward, Document, Move, 1)
///
/// The `repeat` field enables vim-style commands: 3w = (Forward, Word, Move, 3).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(C)]
pub struct SelectionOp {
    pub direction: SelectionDirection,
    pub step: SelectionStep,
    pub mode: SelectionMode,
    pub repeat: usize,
}

impl SelectionOp {
    #[must_use]
    pub const fn new(
        direction: SelectionDirection,
        step: SelectionStep,
        mode: SelectionMode,
    ) -> Self {
        Self {
            direction,
            step,
            mode,
            repeat: 1,
        }
    }
}

/// Keyboard shortcuts for text editing
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum KeyboardShortcut {
    Copy,      // Ctrl+C
    Cut,       // Ctrl+X
    Paste,     // Ctrl+V
    SelectAll, // Ctrl+A
    Undo,      // Ctrl+Z
    Redo,      // Ctrl+Y or Ctrl+Shift+Z
}

impl KeyboardShortcut {
    /// Map a `(VirtualKeyCode, primary, shift)` triple to a text-editing
    /// shortcut. Returns `None` if the key combination is not a recognized
    /// shortcut or if `primary` is not held. `primary` is the platform's
    /// primary modifier — Cmd on macOS, Ctrl elsewhere — obtained from
    /// `KeyboardState::primary_down()` (MWA-A2: hardcoding Ctrl here made
    /// every editing shortcut dead on macOS).
    #[must_use]
    pub const fn from_key(
        vk: crate::window::VirtualKeyCode,
        primary: bool,
        shift: bool,
    ) -> Option<Self> {
        use crate::window::VirtualKeyCode::{A, C, V, X, Y, Z};
        if !primary {
            return None;
        }
        Some(match vk {
            C => Self::Copy,
            X => Self::Cut,
            V => Self::Paste,
            A => Self::SelectAll,
            Z if shift => Self::Redo,
            Z => Self::Undo,
            Y => Self::Redo,
            _ => return None,
        })
    }
}

/// Default input interpreter: standard desktop keybindings.
///
/// This is the default `InputInterpreterFn` that handles arrow keys, Home/End,
/// Backspace/Delete, Ctrl+C/V/A/Z, mouse clicks, and drag selection.
/// Replace it on `LayoutWindow` to implement vim, game controls, etc.
/// `extern "C"` trampoline for `default_input_interpreter`.
#[allow(clippy::not_unsafe_ptr_arg_deref)]
// SAFETY/FFI: `*const T` is the C-ABI signature; the fn null-checks then derefs under the documented caller contract (C guarantees a valid ptr/len). Marking it `unsafe fn` would force unsafe blocks into the generated dll bindings.
#[must_use]
pub extern "C" fn default_input_interpreter_extern(
    _user_data: crate::refany::RefAny,
    info_ptr: *const InputInterpreterInfo<'static>,
) -> PreCallbackFilterResult {
    if info_ptr.is_null() {
        return PreCallbackFilterResult {
            system_changes: Vec::new(),
            user_events: Vec::new(),
        };
    }
    let info = unsafe { &*info_ptr };
    default_input_interpreter(info)
}

/// `extern "C"` trampoline for `default_post_filter`.
#[must_use]
pub extern "C" fn default_post_filter_extern(
    _user_data: crate::refany::RefAny,
    prevent_default: bool,
    pre_changes: SystemChangeVecSlice,
    old_focus: DomNodeId,
    new_focus: DomNodeId,
) -> SystemChangeVec {
    let pre_changes_slice = pre_changes.as_slice();
    let old = old_focus.node.into_crate_internal().map(|_| old_focus);
    let new = new_focus.node.into_crate_internal().map(|_| new_focus);
    default_post_filter(prevent_default, pre_changes_slice, old, new).into()
}

#[must_use]
pub fn default_input_interpreter(info: &InputInterpreterInfo<'_>) -> PreCallbackFilterResult {
    let ctx = FilterContext {
        hit_test: info.hit_test,
        keyboard_state: info.keyboard_state,
        mouse_state: info.mouse_state,
        click_count: info.state.click_count,
        focused_node: info.state.focused_node,
        drag_start_position: info.state.drag_start_position,
        focus_is_editable: info.state.focus_is_editable,
        seat_focus: info.seat_focus,
    };

    let (system_changes, user_events) = info.events.iter().fold(
        (Vec::new(), Vec::new()),
        |(mut internal, mut user), event| {
            match process_event_for_internal(&ctx, event) {
                Some(InternalEventAction::AddAndSkip(evt)) => {
                    internal.push(evt);
                }
                Some(InternalEventAction::AddAndPass(evt)) => {
                    internal.push(evt);
                    user.push(event.clone());
                }
                None => {
                    user.push(event.clone());
                }
            }
            (internal, user)
        },
    );

    PreCallbackFilterResult {
        system_changes,
        user_events,
    }
}

/// Backward-compatible wrapper that calls `default_input_interpreter`.
pub fn pre_callback_filter_internal_events<SM, FM>(
    events: &[SyntheticEvent],
    hit_test: Option<&FullHitTest>,
    keyboard_state: &crate::window::KeyboardState,
    mouse_state: &crate::window::MouseState,
    selection_manager: &SM,
    focus_manager: &FM,
    // See `InputInterpreterState::focus_is_editable` - only a text-editing
    // focus owns the arrow keys.
    focus_is_editable: bool,
) -> PreCallbackFilterResult
where
    SM: SelectionManagerQuery,
    FM: FocusManagerQuery,
{
    let seat_focus = seat_focus_of_events(events, focus_manager);
    let info = InputInterpreterInfo {
        events,
        hit_test,
        keyboard_state,
        mouse_state,
        seat_focus: &seat_focus,
        state: InputInterpreterState {
            focused_node: focus_manager.get_focused_node_id(),
            click_count: selection_manager.get_click_count(),
            drag_start_position: selection_manager.get_drag_start_position(),
            has_selection: selection_manager.has_selection(),
            focus_is_editable,
        },
    };
    default_input_interpreter(&info)
}

/// Context for filtering internal events (used by `default_input_interpreter`)
struct FilterContext<'a> {
    hit_test: Option<&'a FullHitTest>,
    keyboard_state: &'a crate::window::KeyboardState,
    mouse_state: &'a crate::window::MouseState,
    click_count: u8,
    focused_node: Option<DomNodeId>,
    drag_start_position: Option<LogicalPosition>,
    /// See `InputInterpreterState::focus_is_editable`.
    focus_is_editable: bool,
    /// See `InputInterpreterInfo::seat_focus`.
    seat_focus: &'a [(u64, Option<DomNodeId>)],
}

impl FilterContext<'_> {
    /// The focus a key event of seat `seat_id` acts on (9b-ii-a-i-d).
    fn focused_node_for(&self, seat_id: u64) -> Option<DomNodeId> {
        if seat_id == crate::window::PRIMARY_POINTER_SEAT {
            return self.focused_node;
        }
        self.seat_focus
            .iter()
            .find(|(seat, _)| *seat == seat_id)
            .map_or(self.focused_node, |(_, focus)| *focus)
    }
}

/// Process a single event and determine if it generates an internal event
fn process_event_for_internal(
    ctx: &FilterContext<'_>,
    event: &SyntheticEvent,
) -> Option<InternalEventAction> {
    match event.event_type {
        EventType::MouseDown => handle_mouse_down(
            event,
            ctx.hit_test,
            ctx.click_count,
            ctx.mouse_state,
            ctx.keyboard_state,
        ),
        // Drag-selection needs MOVEMENT while the button is down, so it
        // follows `MouseMove`. Leaving it on `MouseOver` after that event
        // became entry-only would have silently killed drag-to-select: the
        // handler would fire once on entry and never again.
        EventType::MouseMove => handle_mouse_move(
            event,
            ctx.hit_test,
            ctx.mouse_state,
            ctx.drag_start_position,
        ),
        EventType::KeyDown => {
            // A seat's key acts on THAT seat's focus (9b-ii-a-i-d).
            let seat_id = match &event.data {
                EventData::Keyboard(k) => k.seat_id,
                _ => crate::window::PRIMARY_POINTER_SEAT,
            };
            handle_key_down(
                event,
                ctx.keyboard_state,
                ctx.focused_node_for(seat_id),
                ctx.focus_is_editable,
            )
        }
        EventType::MouseUp => Some(handle_mouse_up()),
        _ => None,
    }
}

/// Releasing the button ends a text-selection drag, so the autoscroll timer
/// has to go.
///
/// `StopAutoScrollTimer` existed and was handled, but NOTHING emitted it:
/// teardown relied entirely on the 60Hz callback noticing on its next tick
/// that the button had been released and terminating itself. Any path that
/// loses the release — a grab broken by the window manager, a crossing that
/// swallows it — left a timer running at 60Hz for the life of the window.
///
/// It passes to callbacks: a `MouseUp` is a user event, and stopping an
/// internal timer must not swallow it.
const fn handle_mouse_up() -> InternalEventAction {
    InternalEventAction::AddAndPass(SystemChange::StopAutoScrollTimer)
}

/// Action to take after processing an event for internal system events
enum InternalEventAction {
    /// Add system change and skip passing to user callbacks
    AddAndSkip(SystemChange),
    /// Add system change but also pass to user callbacks
    AddAndPass(SystemChange),
}

/// Extract the front-most hovered node from a hit test.
///
/// Picks the node with the minimum `hit_depth` (0 = frontmost/topmost in
/// z-order) across every hovered DOM. The previous implementation took the
/// first entry of the `BTreeMap` (lowest `NodeId`), which ignored z-order
/// entirely and targeted the back-most node under overlapping elements.
/// Ties are broken deterministically by (`DomId`, `NodeId`) iteration order.
fn get_first_hovered_node(hit_test: Option<&FullHitTest>) -> Option<DomNodeId> {
    let ht = hit_test?;
    let mut best: Option<(DomId, NodeId, u32)> = None;
    for (dom_id, hit_data) in &ht.hovered_nodes {
        for (node_id, item) in &hit_data.regular_hit_test_nodes {
            let is_better = match best {
                None => true,
                Some((_, _, best_depth)) => item.hit_depth < best_depth,
            };
            if is_better {
                best = Some((*dom_id, *node_id, item.hit_depth));
            }
        }
    }
    let (dom_id, node_id, _) = best?;
    Some(DomNodeId {
        dom: dom_id,
        node: NodeHierarchyItemId::from_crate_internal(Some(node_id)),
    })
}

/// Extract mouse position from event data, falling back to `mouse_state` if not available
fn get_mouse_position_with_fallback(
    event: &SyntheticEvent,
    mouse_state: &crate::window::MouseState,
) -> LogicalPosition {
    match &event.data {
        EventData::Mouse(mouse_data) => mouse_data.position,
        _ => {
            // Fallback: use current cursor position from mouse_state
            // This handles synthetic events from debug API and automation
            // where EventData may not contain the mouse position
            mouse_state
                .cursor_position
                .get_position()
                .unwrap_or(LogicalPosition::zero())
        }
    }
}

/// Handle `MouseDown` event - detect text selection clicks and Ctrl+Click for multi-cursor
fn handle_mouse_down(
    event: &SyntheticEvent,
    hit_test: Option<&FullHitTest>,
    click_count: u8,
    mouse_state: &crate::window::MouseState,
    keyboard_state: &crate::window::KeyboardState,
) -> Option<InternalEventAction> {
    let effective_click_count = if click_count == 0 { 1 } else { click_count };

    if effective_click_count > 3 {
        return None;
    }

    let _target = get_first_hovered_node(hit_test)?;
    let position = get_mouse_position_with_fallback(event, mouse_state);

    // Ctrl+Click (or Cmd+Click on macOS): add cursor at click position.
    // Use the platform PRIMARY modifier so this fires on Cmd on macOS
    // (where Ctrl+Click is the secondary-click gesture) — `ctrl_down()`
    // was wrong there.
    if keyboard_state.primary_down() && effective_click_count == 1 {
        return Some(InternalEventAction::AddAndPass(
            SystemChange::AddCursorAtClick { position },
        ));
    }

    Some(InternalEventAction::AddAndPass(
        SystemChange::TextSelectionClick {
            position,
            timestamp: event.timestamp.clone(),
        },
    ))
}

/// Handle `MouseMove` event - detect drag selection
fn handle_mouse_move(
    event: &SyntheticEvent,
    _hit_test: Option<&FullHitTest>,
    mouse_state: &crate::window::MouseState,
    drag_start_position: Option<LogicalPosition>,
) -> Option<InternalEventAction> {
    if !mouse_state.left_down {
        return None;
    }

    let start_position = drag_start_position?;

    // Deliberately NOT gated on a hovered hit node. A drag that leaves the
    // text — into the container's padding, over a gap, past the last line —
    // still extends the selection in every native editor, and the endpoint is
    // resolved from the pointer position against the ANCHOR block's layout
    // (`process_mouse_drag_for_selection`), not from whatever happens to be
    // under the cursor. Requiring a hit node froze the selection exactly where
    // the user was reaching for more of it.
    let current_position = get_mouse_position_with_fallback(event, mouse_state);

    Some(InternalEventAction::AddAndPass(
        SystemChange::TextSelectionDrag {
            start_position,
            current_position,
        },
    ))
}

/// Handle `KeyDown` event - detect shortcuts, arrow keys, and delete keys
fn handle_key_down(
    event: &SyntheticEvent,
    keyboard_state: &crate::window::KeyboardState,
    focused_node: Option<DomNodeId>,
    focus_is_editable: bool,
) -> Option<InternalEventAction> {
    use crate::window::VirtualKeyCode;

    let target = focused_node?;
    let EventData::Keyboard(kbd) = &event.data else {
        return None;
    };

    // Read the key and modifiers from THIS event's payload, not from the live
    // `keyboard_state`. The live state can have advanced (another key pressed /
    // released) between when the event was queued and when it is dispatched, so
    // reading it here could act on the wrong key/modifiers. `keyboard_state` is
    // retained only for the platform where the event does not carry a key.
    let _ = keyboard_state;

    // MWA-A2: standard shortcuts key off the PRIMARY modifier (Cmd on
    // macOS, Ctrl elsewhere); word-jump / word-delete keys off the
    // platform's word modifier (Option on macOS, Ctrl elsewhere).
    let primary = if cfg!(target_os = "macos") {
        kbd.modifiers.meta
    } else {
        kbd.modifiers.ctrl
    };
    let word_mod = if cfg!(target_os = "macos") {
        kbd.modifiers.alt
    } else {
        kbd.modifiers.ctrl
    };
    let shift = kbd.modifiers.shift;
    let vk_owned = VirtualKeyCode::from_u32(kbd.key_code)?;
    let vk = &vk_owned;

    // Check keyboard shortcuts (primary+key) → emit specific SystemChange
    // variants. Standard editing shortcuts are routed through the
    // `KeyboardShortcut` enum, and a couple of additional Azul-specific
    // primary-modifier combos are matched after.
    if primary {
        if let Some(shortcut) = KeyboardShortcut::from_key(*vk, primary, shift) {
            // A second seat's shortcut acts on ITS caret (9b-ii-a-i-d-ii-b-i).
            if kbd.seat_id != crate::window::PRIMARY_POINTER_SEAT {
                return Some(InternalEventAction::AddAndSkip(SystemChange::SeatShortcut {
                    seat_id: kbd.seat_id,
                    target,
                    shortcut,
                }));
            }
            let change = match shortcut {
                KeyboardShortcut::Copy => SystemChange::CopyToClipboard,
                KeyboardShortcut::Cut => SystemChange::CutToClipboard { target },
                KeyboardShortcut::Paste => SystemChange::PasteFromClipboard,
                KeyboardShortcut::SelectAll => SystemChange::SelectAllText,
                KeyboardShortcut::Undo => SystemChange::UndoTextEdit { target },
                KeyboardShortcut::Redo => SystemChange::RedoTextEdit { target },
            };
            return Some(InternalEventAction::AddAndSkip(change));
        }
        if matches!(vk, VirtualKeyCode::D) {
            // Ctrl+D adds a multi-cursor, which is the primary's alone
            // (9b-ii-a-i-d-ii-b-i): a seat's passes through to callbacks.
            if kbd.seat_id != crate::window::PRIMARY_POINTER_SEAT {
                return None;
            }
            return Some(InternalEventAction::AddAndSkip(
                SystemChange::SelectNextOccurrence { target },
            ));
        }
    }

    // Unified: arrow keys, Home/End, Backspace/Delete all map to SelectionOp.
    let mode_for_shift = if shift {
        SelectionMode::Extend
    } else {
        SelectionMode::Move
    };
    let selection_op = if let Some(arrow) = ArrowDirection::from_key(*vk, word_mod) {
        // ONLY a text-editing context owns the arrows. Anywhere else they
        // belong to the focused widget (a slider steps its value, a colour
        // plane moves its marker) and, failing that, to the scroll default
        // action. Claiming them here returned `AddAndSkip`, which swallowed
        // the key before any callback could see it.
        if !focus_is_editable {
            return None;
        }
        let (direction, step) = arrow.to_selection(word_mod);
        SelectionOp::new(direction, step, mode_for_shift)
    } else {
        match vk {
            // Backspace/Delete = Delete mode (word modifier upgrades to
            // Word: Option+Backspace on macOS, Ctrl+Backspace elsewhere)
            VirtualKeyCode::Back => SelectionOp::new(
                SelectionDirection::Backward,
                if word_mod {
                    SelectionStep::Word
                } else {
                    SelectionStep::Character
                },
                SelectionMode::Delete,
            ),
            VirtualKeyCode::Delete => SelectionOp::new(
                SelectionDirection::Forward,
                if word_mod {
                    SelectionStep::Word
                } else {
                    SelectionStep::Character
                },
                SelectionMode::Delete,
            ),
            _ => return None,
        }
    };

    Some(InternalEventAction::AddAndSkip(
        SystemChange::ApplySelectionOp {
            target,
            op: selection_op,
            seat_id: kbd.seat_id,
        },
    ))
}

/// Trait for querying selection manager state.
///
/// This allows `pre_callback_filter_internal_events` to query manager state
/// without depending on the concrete `SelectionManager` type from layout crate.
pub trait SelectionManagerQuery {
    /// Get the current click count (1 = single, 2 = double, 3 = triple)
    fn get_click_count(&self) -> u8;

    /// Get the drag start position if a drag is in progress
    fn get_drag_start_position(&self) -> Option<LogicalPosition>;

    /// Check if any selection exists (click selection or drag selection)
    fn has_selection(&self) -> bool;
}

/// Trait for querying focus manager state.
///
/// This allows `pre_callback_filter_internal_events` to query manager state
/// without depending on the concrete `FocusManager` type from layout crate.
pub trait FocusManagerQuery {
    /// Get the currently focused node ID
    fn get_focused_node_id(&self) -> Option<DomNodeId>;

    /// The node seat `seat_id` focuses (9b-ii-a-i-d). A manager without
    /// per-seat focus answers the shared one for every seat.
    fn get_focused_node_for_seat(&self, seat_id: u64) -> Option<DomNodeId> {
        let _ = seat_id;
        self.get_focused_node_id()
    }
}

/// The focused node of every NON-primary keyboard seat that `events` carry
/// (9b-ii-a-i-d), for `InputInterpreterInfo::seat_focus`: the interpreter
/// resolves a seat's key against that seat's focus, not the primary's.
#[must_use]
pub fn seat_focus_of_events<FM: FocusManagerQuery + ?Sized>(
    events: &[SyntheticEvent],
    focus_manager: &FM,
) -> Vec<(u64, Option<DomNodeId>)> {
    let mut out: Vec<(u64, Option<DomNodeId>)> = Vec::new();
    for event in events {
        let EventData::Keyboard(k) = &event.data else {
            continue;
        };
        if k.seat_id == crate::window::PRIMARY_POINTER_SEAT
            || out.iter().any(|(seat, _)| *seat == k.seat_id)
        {
            continue;
        }
        out.push((k.seat_id, focus_manager.get_focused_node_for_seat(k.seat_id)));
    }
    out
}

/// Post-callback filter: Determine additional system changes needed after user callbacks.
///
/// Takes the pre-callback system changes and focus state to determine what
/// post-callback system changes are needed (text input, scrolling, timers).
/// Default post-callback filter: scroll-into-view after cursor ops, auto-scroll during drag.
#[must_use]
pub fn default_post_filter(
    prevent_default: bool,
    pre_changes: &[SystemChange],
    old_focus: Option<DomNodeId>,
    new_focus: Option<DomNodeId>,
) -> Vec<SystemChange> {
    post_callback_filter_system_changes(prevent_default, pre_changes, old_focus, new_focus)
}

// SystemChange dispatch table; a few arms incidentally push the same follow-up
// change but are kept as distinct documented cases.
#[allow(clippy::match_same_arms)]
#[must_use]
pub fn post_callback_filter_system_changes(
    prevent_default: bool,
    pre_changes: &[SystemChange],
    old_focus: Option<DomNodeId>,
    new_focus: Option<DomNodeId>,
) -> Vec<SystemChange> {
    let mut changes = Vec::new();

    if prevent_default {
        // Only focus change passes through preventDefault
        if old_focus != new_focus {
            changes.push(SystemChange::SetFocus {
                new_focus,
                old_focus,
                // A focus move a callback made (or that survived
                // preventDefault) is programmatic, not a keyboard walk: focused
                // but not indicated, like `autofocus`.
                visible: false,
            });
        }
        return changes;
    }

    // Always apply pending text input
    changes.push(SystemChange::ApplyPendingTextInput);

    // Determine post-callback actions based on pre-callback system changes
    for change in pre_changes {
        match change {
            SystemChange::TextSelectionClick { .. }
            | SystemChange::ApplySelectionOp { .. }
            | SystemChange::AddCursorAtClick { .. }
            | SystemChange::SelectNextOccurrence { .. } => {
                changes.push(SystemChange::ScrollSelectionIntoView);
            }
            SystemChange::TextSelectionDrag { .. } => {
                changes.push(SystemChange::StartAutoScrollTimer);
            }
            SystemChange::CutToClipboard { .. }
            | SystemChange::PasteFromClipboard
            | SystemChange::UndoTextEdit { .. }
            | SystemChange::RedoTextEdit { .. }
            | SystemChange::SelectAllText => {
                changes.push(SystemChange::ScrollSelectionIntoView);
            }
            // Other system changes don't generate post-callback actions
            _ => {}
        }
    }

    // Focus changed during callbacks
    if old_focus != new_focus {
        changes.push(SystemChange::SetFocus {
            new_focus,
            old_focus,
            visible: false,
        });
    }

    changes
}

#[cfg(test)]
#[path = "events_test.rs"]
mod events_test;