tessera_ui/

renderer.rs

//! The core rendering system for the Tessera UI framework. This module provides
//! the main [`Renderer`] struct that manages the application lifecycle, event
//! handling, and rendering pipeline for cross-platform UI applications.

pub mod composite;
pub mod compute;
pub mod core;
pub mod drawer;
pub mod external;

use std::sync::{
    Arc,
    atomic::{AtomicBool, Ordering},
};

pub use core::{RenderCore, RenderResources};

use accesskit::{self, TreeUpdate};
use accesskit_winit::{Adapter as AccessKitAdapter, Event as AccessKitEvent};
use parking_lot::RwLock;
use tracing::{debug, error, instrument, warn};
use winit::{
    application::ApplicationHandler,
    error::EventLoopError,
    event::WindowEvent,
    event_loop::{ActiveEventLoop, ControlFlow, EventLoop},
    window::{ResizeDirection, Window, WindowId},
};

use crate::{
    ImeRequest, ImeState, PxPosition,
    build_tree::build_component_tree,
    component_tree::{LayoutFrameDiagnostics, WindowRequests, clear_layout_snapshots},
    context::{reset_component_context_tracking, reset_context_read_dependencies},
    cursor::{
        CursorEventContent, CursorState, GestureState, MOUSE_POINTER_ID, PointerChange,
        PressKeyEventType,
    },
    dp::SCALE_FACTOR,
    focus::{FocusDirection, flush_pending_focus_callbacks},
    keyboard_state::KeyboardState,
    pipeline_context::PipelineContext,
    plugin::{DesktopPlatformContext, DesktopWindowAction, PluginContext, PluginHost},
    px::PxSize,
    render_graph::{RenderGraph, RenderGraphExecution},
    render_module::RenderModule,
    runtime::{
        TesseraRuntime, begin_frame_clock, clear_persistent_focus_handles, clear_redraw_waker,
        has_pending_build_invalidations, has_pending_frame_nanos_receivers, install_redraw_waker,
        reset_build_invalidations, reset_component_replay_tracking, reset_focus_read_dependencies,
        reset_frame_clock, reset_layout_dirty_tracking, reset_render_slot_read_dependencies,
        reset_state_read_dependencies, retain_persistent_focus_handles, take_layout_dirty_nodes,
        tick_frame_nanos_receivers,
    },
    thread_utils,
    time::Instant,
};

pub use crate::render_scene::{Command, DrawRegion, PaddingRect, SampleRegion};

use self::core::RenderTimingBreakdown;

pub use compute::{
    ComputablePipeline, ComputeBatchItem, ComputePipelineRegistry, ErasedComputeBatchItem,
};
pub use drawer::{DrawCommand, DrawablePipeline, PipelineRegistry};
pub use external::{ExternalTextureHandle, ExternalTextureRegistry};

#[cfg(feature = "debug-dirty-overlay")]
use crate::PxRect;
#[cfg(feature = "debug-dirty-overlay")]
use crate::build_tree::{BuildTreeMode, BuildTreeResult};

#[cfg(feature = "profiling")]
use crate::profiler::{
    FrameMeta, Phase as ProfilerPhase, RedrawReason, RuntimeEventKind, RuntimeMeta,
    ScopeGuard as ProfilerScopeGuard, WakeMeta, WakeSource, begin_frame as profiler_begin_frame,
    end_frame as profiler_end_frame, submit_frame_meta, submit_runtime_meta, submit_wake_meta,
};
#[cfg(feature = "profiling")]
use crate::runtime::frame_delta;
#[cfg(feature = "profiling")]
use std::collections::BTreeSet;
#[cfg(feature = "profiling")]
use std::path::PathBuf;

#[cfg(target_family = "wasm")]
use std::{cell::RefCell, rc::Rc};
#[cfg(target_family = "wasm")]
use wasm_bindgen_futures::spawn_local;
#[cfg(target_family = "wasm")]
use web_sys::HtmlCanvasElement;
#[cfg(target_family = "wasm")]
use web_sys::wasm_bindgen::JsCast;
#[cfg(target_family = "wasm")]
use winit::platform::web::EventLoopExtWebSys;

#[cfg(target_os = "android")]
use winit::platform::android::{
    ActiveEventLoopExtAndroid, EventLoopBuilderExtAndroid, activity::AndroidApp,
};

#[derive(Debug)]
enum RendererUserEvent {
    AccessKit(AccessKitEvent),
    RuntimeRedrawWake,
    #[cfg(target_family = "wasm")]
    WebInitReady(u64),
}

impl From<AccessKitEvent> for RendererUserEvent {
    fn from(event: AccessKitEvent) -> Self {
        Self::AccessKit(event)
    }
}

type RenderComputationOutput = (
    RenderGraph,
    WindowRequests,
    std::time::Duration,
    LayoutFrameDiagnostics,
    std::time::Duration,
    Option<FocusDirection>,
    bool,
);

#[derive(Clone, Copy, Debug, Default)]
struct RuntimePendingWork {
    invalidation_pending: bool,
    frame_receiver_pending: bool,
}

impl RuntimePendingWork {
    fn requires_redraw(self) -> bool {
        self.invalidation_pending || self.frame_receiver_pending
    }

    #[cfg(feature = "profiling")]
    fn redraw_reasons(self) -> Vec<RedrawReason> {
        let mut reasons = Vec::new();
        if self.invalidation_pending {
            reasons.push(RedrawReason::RuntimeInvalidation);
        }
        if self.frame_receiver_pending {
            reasons.push(RedrawReason::RuntimeFrameAwaiter);
        }
        reasons
    }
}

#[cfg(feature = "profiling")]
fn resolve_profiler_output_path(config: &TesseraConfig) -> PathBuf {
    if let Ok(path) = std::env::var("TESSERA_PROFILING_OUTPUT")
        && !path.trim().is_empty()
    {
        return PathBuf::from(path);
    }
    if let Some(path) = option_env!("TESSERA_PROFILING_OUTPUT")
        && !path.trim().is_empty()
    {
        return PathBuf::from(path);
    }
    config.profiler_output_path.clone()
}

/// Window creation options for desktop platforms.
#[derive(Debug, Clone)]
pub struct WindowConfig {
    /// Whether to show the system window decorations (title bar and borders).
    pub decorations: bool,
    /// Whether the window supports transparency.
    pub transparent: bool,
    /// Whether the window is resizable.
    pub resizable: bool,
}

impl Default for WindowConfig {
    fn default() -> Self {
        Self {
            decorations: true,
            transparent: true,
            resizable: true,
        }
    }
}

/// Web host configuration for browser platforms.
#[derive(Debug, Clone, Default)]
pub struct WebConfig {
    /// An optional canvas element id to mount into before falling back to the
    /// default body append behavior.
    pub canvas_id: Option<String>,
}

impl WebConfig {
    /// Returns a config that looks up the canvas with the provided id.
    pub fn with_canvas_id(mut self, canvas_id: impl Into<String>) -> Self {
        self.canvas_id = Some(canvas_id.into());
        self
    }
}

/// Configuration for the Tessera runtime and renderer.
///
/// This struct allows you to customize various aspects of the renderer's
/// behavior, including anti-aliasing settings and other rendering parameters.
///
/// # Examples
///
/// ```
/// use tessera_ui::renderer::TesseraConfig;
///
/// // Default configuration (4x MSAA)
/// let config = TesseraConfig::default();
///
/// // Custom configuration with 8x MSAA
/// let config = TesseraConfig {
///     sample_count: 8,
///     ..Default::default()
/// };
///
/// // Disable MSAA for better performance
/// let config = TesseraConfig {
///     sample_count: 1,
///     ..Default::default()
/// };
/// ```
#[derive(Debug, Clone)]
pub struct TesseraConfig {
    /// The number of samples to use for Multi-Sample Anti-Aliasing (MSAA).
    ///
    /// MSAA helps reduce aliasing artifacts (jagged edges) in rendered graphics
    /// by sampling multiple points per pixel and averaging the results.
    ///
    /// ## Supported Values
    /// - `1`: Disables MSAA (best performance, lower quality)
    /// - `4`: 4x MSAA (balanced quality/performance)
    /// - `8`: 8x MSAA (high quality, higher performance cost)
    ///
    /// ## Notes
    /// - Higher sample counts provide better visual quality but consume more
    ///   GPU resources
    /// - The GPU must support the chosen sample count; unsupported values may
    ///   cause errors
    /// - Mobile devices may have limited support for higher sample counts
    /// - Consider using lower values on resource-constrained devices
    pub sample_count: u32,
    /// The title of the application window.
    /// Defaults to "Tessera" if not specified.
    pub window_title: String,
    /// Window configuration (desktop only).
    pub window: WindowConfig,
    /// Web host configuration for browser platforms.
    pub web: WebConfig,
    /// Path to write profiler output when `profiling` is enabled.
    #[cfg(feature = "profiling")]
    pub profiler_output_path: PathBuf,
}

impl Default for TesseraConfig {
    /// Creates a default configuration without MSAA and "Tessera" as the window
    /// title.
    fn default() -> Self {
        Self {
            sample_count: 1,
            window_title: "Tessera".to_string(),
            window: WindowConfig::default(),
            web: WebConfig::default(),
            #[cfg(feature = "profiling")]
            profiler_output_path: PathBuf::from("tessera-profiler.jsonl"),
        }
    }
}

/// # Renderer
///
/// The main renderer struct that manages the application lifecycle and
/// rendering.
///
/// The `Renderer` is the core component of the Tessera UI framework,
/// responsible for:
///
/// - Managing the application window and WGPU context
/// - Handling input events (mouse, touch, keyboard, IME)
/// - Coordinating the component tree building and rendering process
/// - Managing rendering pipelines and resources
///
/// ## Type Parameters
///
/// - `F`: The entry point function type that defines your UI. Must implement
///   `Fn()`.
///
/// ## Lifecycle
///
/// The renderer follows this lifecycle:
/// 1. **Initialization**: Create window, initialize WGPU context, register
///    pipelines
/// 2. **Event Loop**: Handle window events, input events, and render requests
/// 3. **Frame Rendering**: Build component tree → Compute draw commands →
///    Render to surface
/// 4. **Cleanup**: Automatic cleanup when the application exits
///
/// ## Thread Safety
///
/// The renderer runs on the main thread and coordinates frame building,
/// resource management, and event processing from a single UI-thread
/// execution flow.
///
/// ## Usage
///
/// ## Basic Usage
///
/// It's suggested to use `cargo-tessera` to create your project from templates
/// which include all necessary setup. However, here's a minimal example of how
/// to use the renderer through the [`Renderer::run`] method:
///
/// ```no_run
/// use tessera_ui::{PipelineContext, RenderModule, Renderer};
///
/// #[derive(Debug)]
/// struct DemoModule;
///
/// impl RenderModule for DemoModule {
///     fn register_pipelines(&self, _context: &mut PipelineContext<'_>) {}
/// }
///
/// // Define your UI entry point
/// fn my_app() {
///     // Your UI components go here
/// }
///
/// // Run the application
/// Renderer::run(my_app, vec![Box::new(DemoModule)]).unwrap();
/// ```
///
/// ### Android Usage
///
/// On android, [`Renderer::run`] requires an additional `AndroidApp` parameter
/// from app context or `android_main` function.
///
/// ## Configuration
///
/// You can customize the renderer behavior by passing [`TesseraConfig`] when
/// using [`Renderer::run_with_config`]. instead of [`Renderer::run`].
///
/// ```no_run
/// use tessera_ui::{PipelineContext, RenderModule, Renderer, renderer::TesseraConfig};
///
/// # fn foo() -> Result<(), Box<dyn std::error::Error>> {
/// #[derive(Debug)]
/// struct DemoModule;
///
/// impl RenderModule for DemoModule {
///     fn register_pipelines(&self, _context: &mut PipelineContext<'_>) {}
/// }
///
/// let config = TesseraConfig {
///     sample_count: 8,                            // 8x MSAA
///     window_title: "My Tessera App".to_string(), // Custom window title
///     ..Default::default()
/// };
///
/// Renderer::run_with_config(|| { /* my_app */ }, vec![Box::new(DemoModule)], config)?;
/// # Ok(())
/// # }
/// ```
///
/// ## Performance Monitoring
///
/// The renderer includes built-in performance monitoring that logs frame
/// statistics when performance drops below 30 FPS.
pub struct Renderer<F: Fn()> {
    /// The WGPU application context, initialized after window creation
    app: Option<RenderCore>,
    /// The entry point function that defines the root of your UI component tree
    entry_point: F,
    /// Tracks cursor/mouse position and button states
    cursor_state: CursorState,
    /// Tracks keyboard key states and events
    keyboard_state: KeyboardState,
    /// Tracks Input Method Editor (IME) state for international text input
    ime_state: ImeState,
    /// Tracks the renderer-side IME bridge snapshot and platform lifecycle.
    ime_bridge_state: RendererImeBridgeState,
    /// Render modules providing pipelines.
    modules: Vec<Box<dyn RenderModule>>,
    /// Lifecycle hooks for registered plugins.
    plugins: PluginHost,
    /// Configuration settings for the renderer
    config: TesseraConfig,
    /// AccessKit adapter for accessibility support
    accessibility_adapter: Option<AccessKitAdapter>,
    /// Event loop proxy for posting user events (accessibility/runtime wakeups)
    event_loop_proxy: Option<winit::event_loop::EventLoopProxy<RendererUserEvent>>,
    /// Pending programmatic desktop window action requested through plugin
    /// APIs.
    pending_desktop_window_action: Arc<RwLock<Option<DesktopWindowAction>>>,
    /// Incrementing frame index for profiling and debugging.
    frame_index: u64,
    /// Global redraw gate. While `true`, redraw requests are coalesced until
    /// the pending `RedrawRequested` event is consumed.
    redraw_request_pending: Arc<AtomicBool>,
    /// Whether a window close was requested during the last frame.
    pending_close_requested: bool,
    /// Tracks whether a native border resize drag is currently in progress.
    /// While active, cursor input is withheld from the component tree to avoid
    /// accidental UI interaction during system resize.
    resize_in_progress: bool,
    #[cfg(target_family = "wasm")]
    /// Render cores that completed asynchronous initialization on the web
    /// event loop thread and are waiting to be installed into the renderer.
    pending_web_inits: Rc<RefCell<Vec<(u64, RenderCore)>>>,
    #[cfg(target_family = "wasm")]
    /// Monotonic token used to discard stale async initialization completions
    /// after suspend/resume cycles.
    web_init_epoch: u64,
    #[cfg(target_family = "wasm")]
    /// Whether a web-side render core initialization task is currently
    /// running.
    web_init_in_progress: bool,
    #[cfg(feature = "profiling")]
    /// Aggregated redraw reasons that will be attached to the next rendered
    /// frame.
    pending_redraw_reasons: BTreeSet<RedrawReason>,
    #[cfg(target_os = "android")]
    /// Android-specific state tracking whether the soft keyboard is currently
    /// open
    android_ime_opened: bool,
}

impl<F: Fn()> Renderer<F> {
    #[cfg(target_family = "wasm")]
    fn resolve_web_canvas(config: &TesseraConfig) -> Option<HtmlCanvasElement> {
        let canvas_id = config.web.canvas_id.as_deref()?;
        let window = web_sys::window()?;
        let document = window.document()?;
        let element = document.get_element_by_id(canvas_id)?;
        element.dyn_into::<HtmlCanvasElement>().ok()
    }

    /// Runs the Tessera application with default configuration on desktop
    /// platforms.
    ///
    /// This is the most convenient way to start a Tessera application on
    /// Windows, Linux, or macOS. It uses the default [`TesseraConfig`]
    /// settings (4x MSAA).
    ///
    /// # Parameters
    ///
    /// - `entry_point`: A function that defines your UI. This function will be
    ///   called every frame to build the component tree. It should contain your
    ///   root UI components.
    /// - `modules`: Render modules that register pipelines.
    ///
    /// # Returns
    ///
    /// Returns `Ok(())` when the application exits normally, or an
    /// `EventLoopError` if the event loop fails to start or encounters a
    /// critical error.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use tessera_ui::{PipelineContext, RenderModule, Renderer};
    ///
    /// #[derive(Debug)]
    /// struct DemoModule;
    ///
    /// impl RenderModule for DemoModule {
    ///     fn register_pipelines(&self, _context: &mut PipelineContext<'_>) {}
    /// }
    ///
    /// fn my_ui() {
    ///     // Your UI components go here
    /// }
    ///
    /// fn main() -> Result<(), Box<dyn std::error::Error>> {
    ///     Renderer::run(my_ui, vec![Box::new(DemoModule)])?;
    ///     Ok(())
    /// }
    /// ```
    #[cfg(all(not(target_os = "android"), not(target_family = "wasm")))]
    #[tracing::instrument(level = "info", skip(entry_point, modules))]
    pub fn run(entry_point: F, modules: Vec<Box<dyn RenderModule>>) -> Result<(), EventLoopError> {
        Self::run_with_config(entry_point, modules, Default::default())
    }

    /// Runs the Tessera application with custom configuration on desktop
    /// platforms.
    ///
    /// This method allows you to customize the renderer behavior through
    /// [`TesseraConfig`]. Use this when you need to adjust settings like
    /// MSAA sample count or other rendering parameters.
    ///
    /// # Parameters
    ///
    /// - `entry_point`: A function that defines your UI
    /// - `modules`: Render modules that register pipelines
    /// - `config`: Custom configuration for the renderer
    ///
    /// # Returns
    ///
    /// Returns `Ok(())` when the application exits normally, or an
    /// `EventLoopError` if the event loop fails to start.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use tessera_ui::{PipelineContext, RenderModule, Renderer, renderer::TesseraConfig};
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// #[derive(Debug)]
    /// struct DemoModule;
    ///
    /// impl RenderModule for DemoModule {
    ///     fn register_pipelines(&self, _context: &mut PipelineContext<'_>) {}
    /// }
    ///
    /// let config = TesseraConfig {
    ///     sample_count: 8, // 8x MSAA for higher quality
    ///     ..Default::default()
    /// };
    ///
    /// Renderer::run_with_config(|| { /* my_ui */ }, vec![Box::new(DemoModule)], config)?;
    /// # Ok(())
    /// # }
    /// ```
    #[tracing::instrument(level = "info", skip(entry_point, modules))]
    #[cfg(all(not(target_os = "android"), not(target_family = "wasm")))]
    pub fn run_with_config(
        entry_point: F,
        modules: Vec<Box<dyn RenderModule>>,
        config: TesseraConfig,
    ) -> Result<(), EventLoopError> {
        let event_loop = EventLoop::<RendererUserEvent>::with_user_event().build()?;
        let event_loop_proxy = event_loop.create_proxy();
        let app = None;
        let cursor_state = CursorState::default();
        let keyboard_state = KeyboardState::default();
        let ime_state = ImeState::default();
        let ime_bridge_state = RendererImeBridgeState::default();
        #[cfg(feature = "profiling")]
        crate::profiler::set_output_path(resolve_profiler_output_path(&config));
        let mut renderer = Self {
            app,
            entry_point,
            cursor_state,
            keyboard_state,
            modules,
            plugins: PluginHost::new(),
            ime_state,
            ime_bridge_state,
            config,
            accessibility_adapter: None,
            event_loop_proxy: Some(event_loop_proxy),
            pending_desktop_window_action: Arc::new(RwLock::new(None)),
            frame_index: 0,
            redraw_request_pending: Arc::new(AtomicBool::new(false)),
            pending_close_requested: false,
            resize_in_progress: false,
            #[cfg(target_family = "wasm")]
            pending_web_inits: Rc::new(RefCell::new(Vec::new())),
            #[cfg(target_family = "wasm")]
            web_init_epoch: 0,
            #[cfg(target_family = "wasm")]
            web_init_in_progress: false,
            #[cfg(feature = "profiling")]
            pending_redraw_reasons: BTreeSet::new(),
        };
        thread_utils::set_thread_name("TesseraMain");
        event_loop.run_app(&mut renderer)
    }

    /// Runs the Tessera application with default configuration on web
    /// platforms.
    #[cfg(target_family = "wasm")]
    #[tracing::instrument(level = "info", skip(entry_point, modules))]
    pub fn run(entry_point: F, modules: Vec<Box<dyn RenderModule>>) -> Result<(), EventLoopError>
    where
        F: 'static,
    {
        Self::run_web_with_config(entry_point, modules, Default::default())
    }

    /// Runs the Tessera application with custom configuration on web
    /// platforms.
    #[cfg(target_family = "wasm")]
    #[tracing::instrument(level = "info", skip(entry_point, modules))]
    pub fn run_web_with_config(
        entry_point: F,
        modules: Vec<Box<dyn RenderModule>>,
        config: TesseraConfig,
    ) -> Result<(), EventLoopError>
    where
        F: 'static,
    {
        let event_loop = EventLoop::<RendererUserEvent>::with_user_event().build()?;
        let event_loop_proxy = event_loop.create_proxy();
        let app = None;
        let cursor_state = CursorState::default();
        let keyboard_state = KeyboardState::default();
        let ime_state = ImeState::default();
        let ime_bridge_state = RendererImeBridgeState::default();
        #[cfg(feature = "profiling")]
        crate::profiler::set_output_path(resolve_profiler_output_path(&config));
        let renderer = Self {
            app,
            entry_point,
            cursor_state,
            keyboard_state,
            modules,
            plugins: PluginHost::new(),
            ime_state,
            ime_bridge_state,
            config,
            accessibility_adapter: None,
            event_loop_proxy: Some(event_loop_proxy),
            pending_desktop_window_action: Arc::new(RwLock::new(None)),
            frame_index: 0,
            redraw_request_pending: Arc::new(AtomicBool::new(false)),
            pending_close_requested: false,
            resize_in_progress: false,
            pending_web_inits: Rc::new(RefCell::new(Vec::new())),
            web_init_epoch: 0,
            web_init_in_progress: false,
            #[cfg(feature = "profiling")]
            pending_redraw_reasons: BTreeSet::new(),
        };
        thread_utils::set_thread_name("TesseraMain");
        event_loop.spawn_app(renderer);
        Ok(())
    }

    /// Runs the Tessera application with default configuration on Android.
    ///
    /// This method is specifically for Android applications and requires an
    /// `AndroidApp` instance that is typically provided by the
    /// `android_main` function.
    ///
    /// # Parameters
    ///
    /// - `entry_point`: A function that defines your UI
    /// - `modules`: Render modules that register pipelines
    /// - `android_app`: The Android application context
    ///
    /// # Returns
    ///
    /// Returns `Ok(())` when the application exits normally, or an
    /// `EventLoopError` if the event loop fails to start.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use tessera_ui::Renderer;
    /// use winit::platform::android::activity::AndroidApp;
    ///
    /// fn my_ui() {}
    ///
    /// #[derive(Debug)]
    /// struct DemoModule;
    ///
    /// impl tessera_ui::RenderModule for DemoModule {
    ///     fn register_pipelines(&self, _context: &mut tessera_ui::PipelineContext<'_>) {}
    /// }
    ///
    /// #[unsafe(no_mangle)]
    /// fn android_main(android_app: AndroidApp) {
    ///     Renderer::run(my_ui, vec![Box::new(DemoModule)], android_app).unwrap();
    /// }
    /// ```
    #[cfg(target_os = "android")]
    #[tracing::instrument(level = "info", skip(entry_point, modules, android_app))]
    pub fn run(
        entry_point: F,
        modules: Vec<Box<dyn RenderModule>>,
        android_app: AndroidApp,
    ) -> Result<(), EventLoopError> {
        Self::run_with_config(entry_point, modules, android_app, Default::default())
    }

    /// Runs the Tessera application with custom configuration on Android.
    ///
    /// This method allows you to customize the renderer behavior on Android
    /// through [`TesseraConfig`].
    ///
    /// # Parameters
    ///
    /// - `entry_point`: A function that defines your UI
    /// - `modules`: Render modules that register pipelines
    /// - `android_app`: The Android application context
    /// - `config`: Custom configuration for the renderer
    ///
    /// # Returns
    ///
    /// Returns `Ok(())` when the application exits normally, or an
    /// `EventLoopError` if the event loop fails to start.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use tessera_ui::{Renderer, renderer::TesseraConfig};
    /// use winit::platform::android::activity::AndroidApp;
    ///
    /// fn my_ui() {}
    ///
    /// #[derive(Debug)]
    /// struct DemoModule;
    ///
    /// impl tessera_ui::RenderModule for DemoModule {
    ///     fn register_pipelines(&self, _context: &mut tessera_ui::PipelineContext<'_>) {}
    /// }
    ///
    /// #[unsafe(no_mangle)]
    /// fn android_main(android_app: AndroidApp) {
    ///     let config = TesseraConfig {
    ///         sample_count: 2, // Lower MSAA for mobile performance
    ///     };
    ///
    ///     Renderer::run_with_config(my_ui, vec![Box::new(DemoModule)], android_app, config).unwrap();
    /// }
    /// ```
    #[cfg(target_os = "android")]
    #[tracing::instrument(level = "info", skip(entry_point, modules, android_app))]
    pub fn run_with_config(
        entry_point: F,
        modules: Vec<Box<dyn RenderModule>>,
        android_app: AndroidApp,
        config: TesseraConfig,
    ) -> Result<(), EventLoopError> {
        let event_loop = EventLoop::<RendererUserEvent>::with_user_event()
            .with_android_app(android_app.clone())
            .build()
            .unwrap();
        let event_loop_proxy = event_loop.create_proxy();
        let app = None;
        let cursor_state = CursorState::default();
        let keyboard_state = KeyboardState::default();
        let ime_state = ImeState::default();
        let ime_bridge_state = RendererImeBridgeState::default();
        #[cfg(feature = "profiling")]
        crate::profiler::set_output_path(resolve_profiler_output_path(&config));
        let mut renderer = Self {
            app,
            entry_point,
            cursor_state,
            keyboard_state,
            modules,
            plugins: PluginHost::new(),
            ime_state,
            ime_bridge_state,
            android_ime_opened: false,
            config,
            accessibility_adapter: None,
            event_loop_proxy: Some(event_loop_proxy),
            pending_desktop_window_action: Arc::new(RwLock::new(None)),
            frame_index: 0,
            redraw_request_pending: Arc::new(AtomicBool::new(false)),
            pending_close_requested: false,
            resize_in_progress: false,
            #[cfg(feature = "profiling")]
            pending_redraw_reasons: BTreeSet::new(),
        };
        thread_utils::set_thread_name("TesseraMain");
        event_loop.run_app(&mut renderer)
    }
}

// Helper struct to group render-frame arguments and reduce parameter count.
// Kept private to this module.
struct RenderFrameArgs<'a> {
    pub cursor_state: &'a mut CursorState,
    pub keyboard_state: &'a mut KeyboardState,
    pub ime_state: &'a mut ImeState,
    pub ime_bridge_state: &'a mut RendererImeBridgeState,
    #[cfg(target_os = "android")]
    pub android_ime_opened: &'a mut bool,
    pub app: &'a mut RenderCore,
    #[cfg(target_os = "android")]
    pub event_loop: &'a ActiveEventLoop,
}

struct RenderFrameContext<'a, F: Fn()> {
    entry_point: &'a F,
    args: &'a mut RenderFrameArgs<'a>,
    accessibility_enabled: bool,
    decorations: bool,
    window_label: &'a str,
    frame_idx: u64,
    #[cfg(feature = "profiling")]
    redraw_reasons: Vec<RedrawReason>,
}

struct RenderFrameOutcome {
    accessibility_update: Option<TreeUpdate>,
    request_window_drag: bool,
    runtime_pending_work: RuntimePendingWork,
    #[cfg(feature = "debug-dirty-overlay")]
    overlay_clear_pending: bool,
}

#[derive(Clone, Debug, Default, PartialEq, Eq)]
struct RendererImeBridgeState {
    current_request: Option<ImeRequest>,
    ime_allowed: bool,
}

#[derive(Clone, Debug, Default, PartialEq, Eq)]
struct RendererImeBridgeUpdate {
    allowed: Option<bool>,
    cursor_area: Option<(PxPosition, PxSize)>,
    request: Option<ImeRequest>,
    snapshot_changed: bool,
}

impl RendererImeBridgeState {
    #[cfg(test)]
    fn request(&self) -> Option<&ImeRequest> {
        self.current_request.as_ref()
    }

    fn reset(&mut self) {
        *self = Self::default();
    }

    fn update_request(&mut self, request: Option<ImeRequest>) -> RendererImeBridgeUpdate {
        let snapshot_changed = self.current_request != request;
        let allowed = (self.ime_allowed != request.is_some()).then_some(request.is_some());
        let cursor_area = request.as_ref().and_then(|next_request| {
            let previous_area = self.current_request.as_ref().and_then(|previous_request| {
                previous_request
                    .position
                    .map(|position| (position, previous_request.size))
            });
            let next_area = next_request
                .position
                .map(|position| (position, next_request.size));
            (previous_area != next_area).then_some(next_area).flatten()
        });

        self.ime_allowed = request.is_some();
        self.current_request = request.clone();

        RendererImeBridgeUpdate {
            allowed,
            cursor_area,
            request,
            snapshot_changed,
        }
    }
}

impl<F: Fn()> Renderer<F> {
    const RESIZE_EDGE_THRESHOLD: f64 = 8.0;
    const MAX_FOCUS_BEYOND_BOUNDS_RETRIES: usize = 8;

    const fn supports_native_window_frame_controls() -> bool {
        !cfg!(any(
            target_family = "wasm",
            target_os = "android",
            target_os = "ios"
        ))
    }

    #[cfg(target_os = "windows")]
    fn update_native_window_shape(&self, window: &Window) {
        use winit::platform::windows::{CornerPreference, WindowExtWindows};

        if self.config.window.decorations {
            window.set_corner_preference(CornerPreference::Default);
            return;
        }

        let preference = if window.is_maximized() || window.fullscreen().is_some() {
            CornerPreference::DoNotRound
        } else {
            CornerPreference::Round
        };
        window.set_corner_preference(preference);
    }

    #[cfg(target_os = "macos")]
    fn update_native_window_shape(&self, window: &Window) {
        use objc2::rc::Retained;
        use objc2_app_kit::NSView;
        use winit::raw_window_handle::{HasWindowHandle, RawWindowHandle};

        let raw_window_handle = match window.window_handle() {
            Ok(handle) => handle.as_raw(),
            Err(err) => {
                warn!("Failed to fetch native window handle: {}", err);
                return;
            }
        };
        let RawWindowHandle::AppKit(appkit) = raw_window_handle else {
            return;
        };

        // SAFETY: The pointer comes from winit's window handle and is valid for
        // the lifetime of this call on the main thread.
        let create_retained = Retained::<NSView>::retain;
        let Some(ns_view) = (unsafe { create_retained(appkit.ns_view.as_ptr().cast()) }) else {
            warn!("Failed to retain NSView from raw window handle");
            return;
        };

        let radius_px = if self.config.window.decorations
            || window.is_maximized()
            || window.fullscreen().is_some()
        {
            0.0
        } else {
            8.0 * window.scale_factor()
        };

        ns_view.setWantsLayer(true);
        let layer = if let Some(layer) = ns_view.layer() {
            layer
        } else {
            let layer = ns_view.makeBackingLayer();
            ns_view.setLayer(Some(&layer));
            layer
        };
        layer.setCornerRadius(radius_px as _);
        layer.setMasksToBounds(radius_px > 0.0);
    }

    #[cfg(not(any(target_os = "windows", target_os = "macos")))]
    fn update_native_window_shape(&self, _window: &Window) {}

    fn should_set_cursor_pos(
        cursor_position: Option<crate::PxPosition>,
        window_width: f64,
        window_height: f64,
        edge_threshold: f64,
    ) -> bool {
        if let Some(pos) = cursor_position {
            let x = pos.x.0 as f64;
            let y = pos.y.0 as f64;
            x > edge_threshold
                && x < window_width - edge_threshold
                && y > edge_threshold
                && y < window_height - edge_threshold
        } else {
            false
        }
    }

    fn cursor_resize_direction(
        cursor_position: Option<crate::PxPosition>,
        window_size: winit::dpi::PhysicalSize<u32>,
        edge_threshold: f64,
    ) -> Option<ResizeDirection> {
        let position = cursor_position?;
        let x = position.x.0 as f64;
        let y = position.y.0 as f64;
        let width = window_size.width as f64;
        let height = window_size.height as f64;

        let near_left = x <= edge_threshold;
        let near_right = x >= width - edge_threshold;
        let near_top = y <= edge_threshold;
        let near_bottom = y >= height - edge_threshold;

        match (near_left, near_right, near_top, near_bottom) {
            (true, _, true, _) => Some(ResizeDirection::NorthWest),
            (_, true, true, _) => Some(ResizeDirection::NorthEast),
            (true, _, _, true) => Some(ResizeDirection::SouthWest),
            (_, true, _, true) => Some(ResizeDirection::SouthEast),
            (true, _, _, _) => Some(ResizeDirection::West),
            (_, true, _, _) => Some(ResizeDirection::East),
            (_, _, true, _) => Some(ResizeDirection::North),
            (_, _, _, true) => Some(ResizeDirection::South),
            _ => None,
        }
    }

    fn cursor_icon_for_resize(direction: ResizeDirection) -> winit::window::CursorIcon {
        match direction {
            ResizeDirection::East | ResizeDirection::West => winit::window::CursorIcon::EwResize,
            ResizeDirection::North | ResizeDirection::South => winit::window::CursorIcon::NsResize,
            ResizeDirection::NorthEast | ResizeDirection::SouthWest => {
                winit::window::CursorIcon::NeswResize
            }
            ResizeDirection::NorthWest | ResizeDirection::SouthEast => {
                winit::window::CursorIcon::NwseResize
            }
        }
    }

    /// Executes a single frame rendering cycle.
    ///
    /// This is the core rendering method that orchestrates the entire frame
    /// rendering process. It follows a three-phase approach:
    ///
    /// 1. **Component Tree Building**: Calls the entry point function to build
    ///    the UI component tree
    /// 2. **Draw Command Computation**: Processes the component tree to
    ///    generate rendering commands
    /// 3. **Surface Rendering**: Executes the commands to render the final
    ///    frame
    ///
    /// ## Performance Monitoring
    ///
    /// This method includes built-in performance monitoring that logs detailed
    /// timing information when frame rates drop below 30 FPS, helping
    /// identify performance bottlenecks.
    ///
    /// ## Parameters
    ///
    /// - `entry_point`: The UI entry point function to build the component tree
    /// - `cursor_state`: Mutable reference to cursor/mouse state for event
    ///   processing
    /// - `keyboard_state`: Mutable reference to keyboard state for event
    ///   processing
    /// - `ime_state`: Mutable reference to IME state for text input processing
    /// - `android_ime_opened`: (Android only) Tracks soft keyboard state
    /// - `app`: Mutable reference to the WGPU application context
    /// - `event_loop`: (Android only) Event loop for IME management
    ///
    /// ## Frame Timing Breakdown
    ///
    /// - **Build Tree Cost**: Time spent building the component tree
    /// - **Draw Commands Cost**: Time spent computing rendering commands
    /// - **Render Cost**: Time spent executing GPU rendering commands
    ///
    /// ## Thread Safety
    ///
    /// This method runs on the main thread but coordinates with other threads
    /// for component tree processing and resource management.
    fn log_frame_stats(
        build_tree_cost: std::time::Duration,
        draw_cost: std::time::Duration,
        render_cost: std::time::Duration,
        render_breakdown: Option<RenderTimingBreakdown>,
    ) {
        let total = build_tree_cost + draw_cost + render_cost;
        let fps = 1.0 / total.as_secs_f32();
        if fps < 30.0 {
            if let Some(breakdown) = render_breakdown {
                warn!(
                    "Jank detected! Frame statistics:
Build tree cost: {:?}
Draw commands cost: {:?}
Render cost: {:?}
Total frame cost: {:?}
Fps: {:.2}
Render breakdown:
Acquire: {:?}
Build passes: {:?}
Encode: {:?}
Submit: {:?}
Present: {:?}
Render total (core): {:?}
",
                    build_tree_cost,
                    draw_cost,
                    render_cost,
                    total,
                    1.0 / total.as_secs_f32(),
                    breakdown.acquire,
                    breakdown.build_passes,
                    breakdown.encode,
                    breakdown.submit,
                    breakdown.present,
                    breakdown.total,
                );
            } else {
                warn!(
                    "Jank detected! Frame statistics:
Build tree cost: {:?}
Draw commands cost: {:?}
Render cost: {:?}
Total frame cost: {:?}
Fps: {:.2}
",
                    build_tree_cost,
                    draw_cost,
                    render_cost,
                    total,
                    1.0 / total.as_secs_f32()
                );
            }
        }
    }

    #[instrument(level = "debug", skip(args))]
    fn compute_draw_commands<'a>(
        args: &mut RenderFrameArgs<'a>,
        screen_size: PxSize,
        frame_idx: u64,
        retry_focus_move: Option<FocusDirection>,
        retry_focus_reveal: bool,
    ) -> RenderComputationOutput {
        let draw_timer = Instant::now();
        debug!("Computing draw commands...");
        let cursor_position = args.cursor_state.position();
        let is_retry = retry_focus_move.is_some() || retry_focus_reveal;
        let pointer_changes = if is_retry {
            Vec::new()
        } else {
            args.cursor_state.take_events()
        };
        let keyboard_events = if is_retry {
            Vec::new()
        } else {
            args.keyboard_state.take_events()
        };
        let ime_events = if is_retry {
            Vec::new()
        } else {
            args.ime_state.take_events()
        };

        // Clear any existing compute resources
        args.app.compute_resource_manager_mut().clear();
        let layout_dirty_nodes = take_layout_dirty_nodes();

        let (
            graph,
            window_requests,
            layout_diagnostics,
            record_cost,
            pending_focus_move_retry,
            pending_focus_reveal_retry,
        ) = TesseraRuntime::with_mut(|rt| {
            let component_tree = &mut rt.component_tree;
            let (gpu, compute_resource_manager) = args.app.record_resources();
            component_tree.compute(
                crate::component_tree::ComputeParams {
                    screen_size,
                    cursor_position,
                    pointer_changes,
                    keyboard_events,
                    ime_events,
                    retry_focus_move,
                    retry_focus_reveal,
                    modifiers: args.keyboard_state.modifiers(),
                    layout_dirty_nodes: &layout_dirty_nodes,
                },
                crate::component_tree::ComputeMode::Full {
                    compute_resource_manager,
                    gpu,
                },
            )
        });
        flush_pending_focus_callbacks();

        let draw_cost = draw_timer.elapsed();
        debug!("Draw commands computed in {draw_cost:?}");
        (
            graph,
            window_requests,
            draw_cost,
            layout_diagnostics,
            record_cost,
            pending_focus_move_retry,
            pending_focus_reveal_retry,
        )
    }

    #[cfg(feature = "debug-dirty-overlay")]
    fn layout_node_overlay_rect(
        metadatas: &crate::component_tree::ComponentNodeMetaDatas,
        node_id: crate::NodeId,
    ) -> Option<PxRect> {
        let metadata = metadatas.get(&node_id)?;
        let abs_position = metadata.abs_position?;
        let computed_data = metadata.computed_data?;
        if computed_data.width.0 <= 0 || computed_data.height.0 <= 0 {
            return None;
        }
        let node_rect = PxRect::from_position_size(
            abs_position,
            PxSize::new(computed_data.width, computed_data.height),
        );
        Some(
            metadata
                .event_clip_rect
                .and_then(|clip_rect| clip_rect.intersection(&node_rect))
                .unwrap_or(node_rect),
        )
    }

    #[cfg(feature = "debug-dirty-overlay")]
    fn collect_dirty_overlay_rects(
        screen_size: PxSize,
        build_tree_result: &BuildTreeResult,
    ) -> Vec<PxRect> {
        use crate::component_tree::{NodeRole, direct_layout_children};

        if matches!(build_tree_result.mode(), BuildTreeMode::SkipNoInvalidation) {
            return Vec::new();
        }
        if matches!(build_tree_result.mode(), BuildTreeMode::RootRecompose) {
            if build_tree_result.had_invalidations() {
                return vec![PxRect::from_position_size(PxPosition::ZERO, screen_size)];
            }
            return Vec::new();
        }
        TesseraRuntime::with(|rt| {
            let tree = rt.component_tree.tree();
            let metadatas = rt.component_tree.metadatas();
            let mut rects = Vec::new();
            for instance_key in build_tree_result.dirty_replay_roots() {
                let Some(node_id) = rt
                    .component_tree
                    .find_node_id_by_instance_key(*instance_key)
                else {
                    continue;
                };
                let layout_nodes = match tree.get(node_id) {
                    Some(node_ref) if node_ref.get().role == NodeRole::Layout => vec![node_id],
                    Some(_) => direct_layout_children(node_id, tree),
                    None => continue,
                };
                for layout_node_id in layout_nodes {
                    if let Some(rect) = Self::layout_node_overlay_rect(metadatas, layout_node_id) {
                        rects.push(rect);
                    }
                }
            }
            rects
        })
    }

    /// Perform the actual GPU rendering for the provided commands and return
    /// the render duration.
    #[cfg(not(feature = "debug-dirty-overlay"))]
    #[instrument(level = "debug", skip(args, execution))]
    fn perform_render<'a>(
        args: &mut RenderFrameArgs<'a>,
        execution: RenderGraphExecution,
    ) -> std::time::Duration {
        #[cfg(feature = "profiling")]
        let _profiler_guard =
            ProfilerScopeGuard::new(ProfilerPhase::RenderFrame, None, None, Some("render_frame"));
        let render_timer = Instant::now();

        // skip actual rendering if window is minimized
        if TesseraRuntime::with(|rt| rt.window_minimized) {
            return render_timer.elapsed();
        }

        debug!("Rendering draw commands...");
        args.app.render(execution);
        let render_cost = render_timer.elapsed();
        debug!("Rendered to surface in {render_cost:?}");
        render_cost
    }

    #[cfg(feature = "debug-dirty-overlay")]
    #[instrument(level = "debug", skip(args, execution, dirty_overlay_rects))]
    fn perform_render<'a>(
        args: &mut RenderFrameArgs<'a>,
        execution: RenderGraphExecution,
        dirty_overlay_rects: &[PxRect],
    ) -> std::time::Duration {
        #[cfg(feature = "profiling")]
        let _profiler_guard =
            ProfilerScopeGuard::new(ProfilerPhase::RenderFrame, None, None, Some("render_frame"));
        let render_timer = Instant::now();

        // skip actual rendering if window is minimized
        if TesseraRuntime::with(|rt| rt.window_minimized) {
            return render_timer.elapsed();
        }

        debug!("Rendering draw commands...");
        args.app.render(execution, dirty_overlay_rects);
        let render_cost = render_timer.elapsed();
        debug!("Rendered to surface in {render_cost:?}");
        render_cost
    }

    #[instrument(level = "debug", skip(context))]
    fn execute_render_frame(context: RenderFrameContext<'_, F>) -> RenderFrameOutcome {
        let RenderFrameContext {
            entry_point,
            args,
            accessibility_enabled,
            decorations,
            window_label,
            frame_idx,
            #[cfg(feature = "profiling")]
            redraw_reasons,
        } = context;
        #[cfg(feature = "profiling")]
        let frame_timer = Instant::now();
        #[cfg(feature = "profiling")]
        profiler_begin_frame(frame_idx);
        begin_frame_clock(Instant::now());
        // Tick frame-nanos receivers before build so their state writes are
        // consumed by the current recomposition pass.
        tick_frame_nanos_receivers();
        // notify the windowing system before rendering
        // this will help winit to properly schedule and make assumptions about its
        // internal state
        args.app.window().pre_present_notify();
        // and tell runtime the new size
        TesseraRuntime::with_mut(|rt: &mut TesseraRuntime| rt.window_size = args.app.size().into());
        // Build the component tree and measure time
        let mut build_tree_result = build_component_tree(entry_point);
        debug!("Component tree build mode: {:?}", build_tree_result.mode());

        // Compute draw commands
        let screen_size: PxSize = args.app.size().into();
        let (
            mut new_graph,
            mut window_requests,
            mut draw_cost,
            mut layout_diagnostics,
            mut record_cost,
            mut pending_focus_move_retry,
            mut pending_focus_reveal_retry,
        ) = Self::compute_draw_commands(args, screen_size, frame_idx, None, false);
        let mut beyond_bounds_retry_count = 0usize;
        while pending_focus_move_retry.is_some() || pending_focus_reveal_retry {
            if beyond_bounds_retry_count >= Self::MAX_FOCUS_BEYOND_BOUNDS_RETRIES
                || !has_pending_build_invalidations()
            {
                break;
            }

            beyond_bounds_retry_count += 1;
            let retry_build = build_component_tree(entry_point);
            build_tree_result.absorb_retry(retry_build);

            let (
                retry_graph,
                retry_window_requests,
                retry_draw_cost,
                retry_layout_diagnostics,
                retry_record_cost,
                next_focus_move_retry,
                next_focus_reveal_retry,
            ) = Self::compute_draw_commands(
                args,
                screen_size,
                frame_idx,
                pending_focus_move_retry,
                pending_focus_reveal_retry,
            );
            new_graph = retry_graph;
            window_requests = retry_window_requests;
            draw_cost += retry_draw_cost;
            layout_diagnostics = retry_layout_diagnostics;
            record_cost += retry_record_cost;
            pending_focus_move_retry = next_focus_move_retry;
            pending_focus_reveal_retry = next_focus_reveal_retry;
        }
        let final_frame_instance_keys =
            TesseraRuntime::with(|runtime| runtime.component_tree.live_instance_keys());
        let removed_focus_handles = retain_persistent_focus_handles(&final_frame_instance_keys);
        if !removed_focus_handles.handle_ids.is_empty()
            || !removed_focus_handles.requester_ids.is_empty()
        {
            TesseraRuntime::with_mut(|runtime| {
                runtime.component_tree.focus_owner_mut().remove_handles(
                    &removed_focus_handles.handle_ids,
                    &removed_focus_handles.requester_ids,
                );
            });
        }
        #[cfg(not(feature = "profiling"))]
        let _ = (layout_diagnostics, record_cost);
        #[cfg(feature = "debug-dirty-overlay")]
        let dirty_overlay_rects =
            Self::collect_dirty_overlay_rects(screen_size, &build_tree_result);
        #[cfg(feature = "debug-dirty-overlay")]
        let overlay_clear_pending = !dirty_overlay_rects.is_empty();
        let (composite_context, composite_registry) =
            args.app.composite_context_parts(screen_size, frame_idx);
        let new_graph =
            composite::expand_composites(new_graph, composite_context, composite_registry);
        let RenderGraphExecution {
            ops,
            resources,
            external_resources,
        } = new_graph.into_execution();
        // Perform GPU render every frame.
        let render_cost = Self::perform_render(
            args,
            RenderGraphExecution {
                ops,
                resources,
                external_resources,
            },
            #[cfg(feature = "debug-dirty-overlay")]
            &dirty_overlay_rects,
        );
        // Log frame statistics
        let render_breakdown = args.app.last_render_breakdown();
        Self::log_frame_stats(
            build_tree_result.duration(),
            draw_cost,
            render_cost,
            render_breakdown,
        );

        #[cfg(feature = "profiling")]
        {
            let render_duration_ns = Some(render_cost.as_nanos());
            let render_acquire_ns = render_breakdown.map(|breakdown| breakdown.acquire.as_nanos());
            let render_build_passes_ns =
                render_breakdown.map(|breakdown| breakdown.build_passes.as_nanos());
            let render_encode_ns = render_breakdown.map(|breakdown| breakdown.encode.as_nanos());
            let render_submit_ns = render_breakdown.map(|breakdown| breakdown.submit.as_nanos());
            let render_present_ns = render_breakdown.map(|breakdown| breakdown.present.as_nanos());
            let frame_total_ns = frame_timer.elapsed().as_nanos();
            let inter_frame_wait_ns = (frame_idx > 0).then(|| frame_delta().as_nanos());
            let nodes = TesseraRuntime::with(|rt| rt.component_tree.profiler_nodes());
            submit_frame_meta(FrameMeta {
                frame_idx,
                build_mode: build_tree_result.profiler_build_mode(),
                redraw_reasons,
                inter_frame_wait_ns,
                partial_replay_nodes: build_tree_result.partial_replay_nodes(),
                total_nodes_before_build: build_tree_result.total_nodes_before_build(),
                render_time_ns: render_duration_ns,
                render_acquire_ns,
                render_build_passes_ns,
                render_encode_ns,
                render_submit_ns,
                render_present_ns,
                build_tree_time_ns: Some(build_tree_result.duration().as_nanos()),
                draw_time_ns: Some(draw_cost.as_nanos()),
                record_time_ns: Some(record_cost.as_nanos()),
                frame_total_ns: Some(frame_total_ns),
                layout_diagnostics: Some(layout_diagnostics),
                nodes,
            });
        }

        // Prepare accessibility tree update before clearing the component tree if
        // needed
        let accessibility_update = if accessibility_enabled {
            Self::build_accessibility_update(window_label)
        } else {
            None
        };

        #[cfg(feature = "profiling")]
        profiler_end_frame();

        // Handle the window requests (cursor / IME)
        // Only set cursor when not at window edges to let window manager handle resize
        // cursors
        let cursor_position = args.cursor_state.position();
        let window_size = args.app.size();
        let resize_direction = (Self::supports_native_window_frame_controls() && !decorations)
            .then(|| {
                Self::cursor_resize_direction(
                    cursor_position,
                    window_size,
                    Self::RESIZE_EDGE_THRESHOLD,
                )
            });

        if let Some(direction) = resize_direction.flatten() {
            let icon = Self::cursor_icon_for_resize(direction);
            args.app
                .window()
                .set_cursor(winit::window::Cursor::Icon(icon));
        } else {
            let should_set_cursor = Self::should_set_cursor_pos(
                cursor_position,
                window_size.width as f64,
                window_size.height as f64,
                Self::RESIZE_EDGE_THRESHOLD,
            );

            if should_set_cursor {
                args.app
                    .window()
                    .set_cursor(winit::window::Cursor::Icon(window_requests.cursor_icon));
            }
        }

        let request_window_drag =
            Self::supports_native_window_frame_controls() && window_requests.request_window_drag;

        let ime_bridge_update = args
            .ime_bridge_state
            .update_request(window_requests.ime_request);
        if let Some(allowed) = ime_bridge_update.allowed {
            #[cfg(not(target_os = "android"))]
            args.app.window().set_ime_allowed(allowed);
            #[cfg(target_os = "android")]
            {
                if allowed {
                    if !*args.android_ime_opened {
                        args.app.window().set_ime_allowed(true);
                        show_soft_input(true, args.event_loop.android_app());
                        *args.android_ime_opened = true;
                    }
                } else if *args.android_ime_opened {
                    args.app.window().set_ime_allowed(false);
                    hide_soft_input(args.event_loop.android_app());
                    *args.android_ime_opened = false;
                }
            }
        }
        if let Some((position, size)) = ime_bridge_update.cursor_area {
            args.app
                .window()
                .set_ime_cursor_area::<PxPosition, PxSize>(position, size);
        } else if ime_bridge_update.snapshot_changed
            && let Some(ime_request) = ime_bridge_update.request
            && ime_request.position.is_none()
        {
            warn!("IME request missing position; skipping IME cursor area update");
        }

        // End of frame cleanup
        args.cursor_state.frame_cleanup();

        let runtime_pending_work = RuntimePendingWork {
            invalidation_pending: has_pending_build_invalidations(),
            frame_receiver_pending: has_pending_frame_nanos_receivers(),
        };

        RenderFrameOutcome {
            accessibility_update,
            request_window_drag,
            runtime_pending_work,
            #[cfg(feature = "debug-dirty-overlay")]
            overlay_clear_pending,
        }
    }
}

impl<F: Fn()> Renderer<F> {
    fn desktop_platform_context(&self) -> Option<DesktopPlatformContext> {
        let app = self.app.as_ref()?;
        let redraw_pending = self.redraw_request_pending.clone();
        let window = app.window_arc();
        let wake_handler = Arc::new(move || {
            Self::try_request_redraw(window.as_ref(), redraw_pending.as_ref());
        });
        Some(DesktopPlatformContext::new(
            app.window_arc(),
            self.pending_desktop_window_action.clone(),
            wake_handler,
        ))
    }

    fn take_pending_desktop_window_action(&self) -> Option<DesktopWindowAction> {
        self.pending_desktop_window_action.write().take()
    }

    #[cfg(target_os = "android")]
    fn plugin_context(&self, event_loop: &ActiveEventLoop) -> Option<PluginContext> {
        let desktop = self.desktop_platform_context()?;
        Some(PluginContext::new(
            desktop,
            event_loop.android_app().clone(),
        ))
    }

    #[cfg(not(target_os = "android"))]
    fn plugin_context(&self, _event_loop: &ActiveEventLoop) -> Option<PluginContext> {
        let desktop = self.desktop_platform_context()?;
        Some(PluginContext::new(desktop))
    }

    fn try_request_redraw(window: &Window, redraw_pending: &AtomicBool) {
        if redraw_pending
            .compare_exchange(false, true, Ordering::AcqRel, Ordering::Acquire)
            .is_ok()
        {
            window.request_redraw();
        }
    }

    fn request_redraw_now(&self) {
        if let Some(app) = self.app.as_ref() {
            Self::try_request_redraw(app.window(), self.redraw_request_pending.as_ref());
        }
    }

    fn install_runtime_redraw_waker(&self) {
        let Some(proxy) = self.event_loop_proxy.clone() else {
            clear_redraw_waker();
            return;
        };
        install_redraw_waker(Arc::new(move || {
            let _ = proxy.send_event(RendererUserEvent::RuntimeRedrawWake);
        }));
    }

    #[cfg(target_family = "wasm")]
    fn begin_web_initialization(&mut self, window: Arc<Window>) {
        let Some(proxy) = self.event_loop_proxy.clone() else {
            error!("Missing event loop proxy for web renderer initialization");
            return;
        };

        self.web_init_in_progress = true;
        let epoch = self.web_init_epoch;
        let pending_web_inits = self.pending_web_inits.clone();
        let sample_count = self.config.sample_count;
        let transparent = self.config.window.transparent;
        spawn_local(async move {
            let render_core = RenderCore::new(window, sample_count, transparent).await;
            pending_web_inits.borrow_mut().push((epoch, render_core));
            let _ = proxy.send_event(RendererUserEvent::WebInitReady(epoch));
        });
    }

    #[cfg(target_family = "wasm")]
    fn finish_web_initialization(&mut self, event_loop: &ActiveEventLoop, epoch: u64) -> bool {
        let pending_render_core = {
            let mut pending_web_inits = self.pending_web_inits.borrow_mut();
            pending_web_inits
                .iter()
                .position(|(ready_epoch, _)| *ready_epoch == epoch)
                .map(|position| pending_web_inits.remove(position).1)
        };
        let Some(mut render_core) = pending_render_core else {
            return false;
        };

        if epoch != self.web_init_epoch {
            return false;
        }

        let mut context = PipelineContext::new(&mut render_core);
        for module in &self.modules {
            module.register_pipelines(&mut context);
        }

        self.app = Some(render_core);
        self.web_init_in_progress = false;
        self.install_runtime_redraw_waker();
        #[cfg(feature = "profiling")]
        self.request_redraw_with_reasons(WakeSource::Lifecycle, vec![RedrawReason::Startup]);
        #[cfg(not(feature = "profiling"))]
        self.request_redraw_now();

        if let Some(context) = self.plugin_context(event_loop) {
            self.plugins.resumed(&context);
        }
        true
    }

    #[cfg(feature = "profiling")]
    fn request_redraw_with_reasons(&mut self, source: WakeSource, mut reasons: Vec<RedrawReason>) {
        reasons.sort_unstable();
        reasons.dedup();
        if reasons.is_empty() {
            return;
        }

        self.pending_redraw_reasons.extend(reasons.iter().copied());

        submit_wake_meta(WakeMeta {
            frame_idx: self.frame_index,
            source,
            reasons: reasons.clone(),
        });

        self.request_redraw_now();
    }

    #[cfg(feature = "profiling")]
    fn take_pending_redraw_reasons(&mut self) -> Vec<RedrawReason> {
        std::mem::take(&mut self.pending_redraw_reasons)
            .into_iter()
            .collect()
    }

    // These keep behavior identical but reduce per-function complexity.
    fn handle_close_requested(&mut self, event_loop: &ActiveEventLoop) {
        if let Some(context) = self.plugin_context(event_loop) {
            self.plugins.shutdown(&context);
        }
        if let Some(ref app) = self.app
            && let Err(e) = app.save_pipeline_cache()
        {
            warn!("Failed to save pipeline cache: {}", e);
        }
        event_loop.exit();
    }

    fn apply_window_drag(&mut self, window: &Window) {
        if !Self::supports_native_window_frame_controls() {
            return;
        }
        if let Err(err) = window.drag_window() {
            warn!("Failed to start window drag: {}", err);
        }
        self.update_native_window_shape(window);
    }

    fn apply_desktop_window_action(&mut self, window: &Window, action: DesktopWindowAction) {
        match action {
            DesktopWindowAction::Minimize => {
                window.set_minimized(true);
            }
            DesktopWindowAction::Maximize => {
                window.set_maximized(true);
            }
            DesktopWindowAction::ToggleMaximize => {
                window.set_maximized(!window.is_maximized());
            }
            DesktopWindowAction::Close => {
                self.pending_close_requested = true;
            }
        }
        self.update_native_window_shape(window);
    }

    fn handle_resized(&mut self, size: winit::dpi::PhysicalSize<u32>) {
        // Obtain the app inside the method to avoid holding a mutable borrow across
        // other borrows of `self`.
        let app = match self.app.as_mut() {
            Some(app) => app,
            None => return,
        };
        let window = app.window_arc();

        if size.width == 0 || size.height == 0 {
            TesseraRuntime::with_mut(|rt| {
                if !rt.window_minimized {
                    rt.window_minimized = true;
                }
            });
        } else {
            TesseraRuntime::with_mut(|rt| {
                if rt.window_minimized {
                    rt.window_minimized = false;
                }
            });
            app.resize(size);
        }
        self.update_native_window_shape(&window);
    }

    fn handle_cursor_moved(&mut self, position: winit::dpi::PhysicalPosition<f64>) {
        if self.resize_in_progress {
            return;
        }
        let px_position = PxPosition::from_f64_arr2([position.x, position.y]);
        // Update cursor position
        self.cursor_state.update_position(px_position);
        self.cursor_state.push_event(PointerChange {
            timestamp: Instant::now(),
            pointer_id: MOUSE_POINTER_ID,
            content: CursorEventContent::Moved(px_position),
            gesture_state: GestureState::TapCandidate,
            consumed: false,
        });
        debug!("Cursor moved to: {}, {}", position.x, position.y);
    }

    fn handle_cursor_left(&mut self) {
        // Clear cursor position when it leaves the window
        // This also set the position to None
        self.cursor_state.clear();
        debug!("Cursor left the window");
    }

    fn push_accessibility_update(&mut self, tree_update: TreeUpdate) {
        if let Some(adapter) = self.accessibility_adapter.as_mut() {
            adapter.update_if_active(|| tree_update);
        }
    }

    fn send_accessibility_update(&mut self) {
        if let Some(tree_update) = Self::build_accessibility_update(&self.config.window_title) {
            self.push_accessibility_update(tree_update);
        }
    }

    fn build_accessibility_update(window_label: &str) -> Option<TreeUpdate> {
        TesseraRuntime::with(|runtime| {
            let tree = runtime.component_tree.tree();
            let metadatas = runtime.component_tree.metadatas();
            let root_node_id = tree.get_node_id_at(
                std::num::NonZero::new(1).expect("root node index must be non-zero"),
            )?;
            crate::accessibility::build_tree_update(
                tree,
                metadatas,
                root_node_id,
                Some(window_label),
            )
        })
    }

    fn handle_mouse_input(
        &mut self,
        state: winit::event::ElementState,
        button: winit::event::MouseButton,
    ) {
        let Some(event_content) = CursorEventContent::from_press_event(state, button) else {
            return; // Ignore unsupported buttons
        };

        if self.resize_in_progress {
            if matches!(
                event_content,
                CursorEventContent::Released(PressKeyEventType::Left)
            ) {
                self.resize_in_progress = false;
            }
            return;
        }

        if matches!(
            event_content,
            CursorEventContent::Pressed(PressKeyEventType::Left)
        ) && Self::supports_native_window_frame_controls()
            && !self.config.window.decorations
            && let Some(app) = self.app.as_ref()
        {
            let window_size = app.size();
            let direction = Self::cursor_resize_direction(
                self.cursor_state.position(),
                window_size,
                Self::RESIZE_EDGE_THRESHOLD,
            );
            if let Some(direction) = direction {
                if let Err(err) = app.window().drag_resize_window(direction) {
                    warn!("Failed to start window resize: {}", err);
                } else {
                    self.resize_in_progress = true;
                    self.cursor_state.clear();
                    debug!("Started native border resize; suppressing cursor input");
                }
                return;
            }
        }
        let event = PointerChange {
            timestamp: Instant::now(),
            pointer_id: MOUSE_POINTER_ID,
            content: event_content,
            gesture_state: GestureState::TapCandidate,
            consumed: false,
        };
        self.cursor_state.push_event(event);
        debug!("Mouse input: {state:?} button {button:?}");
    }

    fn handle_mouse_wheel(&mut self, delta: winit::event::MouseScrollDelta) {
        if self.resize_in_progress {
            return;
        }
        let event_content = CursorEventContent::from_scroll_event(delta);
        let event = PointerChange {
            timestamp: Instant::now(),
            pointer_id: MOUSE_POINTER_ID,
            content: event_content,
            gesture_state: GestureState::Dragged,
            consumed: false,
        };
        self.cursor_state.push_event(event);
        debug!("Mouse scroll: {delta:?}");
    }

    fn handle_touch(&mut self, touch_event: winit::event::Touch) {
        if self.resize_in_progress {
            return;
        }
        let pos = PxPosition::from_f64_arr2([touch_event.location.x, touch_event.location.y]);
        debug!(
            "Touch event: id {}, phase {:?}, position {:?}",
            touch_event.id, touch_event.phase, pos
        );
        match touch_event.phase {
            winit::event::TouchPhase::Started => {
                // Use new touch start handling method
                self.cursor_state.handle_touch_start(touch_event.id, pos);
            }
            winit::event::TouchPhase::Moved => {
                // Use new touch move handling method, may generate scroll event
                if let Some(scroll_event) = self.cursor_state.handle_touch_move(touch_event.id, pos)
                {
                    // Scroll event is already added to event queue in handle_touch_move
                    self.cursor_state.push_event(scroll_event);
                }
            }
            winit::event::TouchPhase::Ended | winit::event::TouchPhase::Cancelled => {
                // Use new touch end handling method
                self.cursor_state.handle_touch_end(touch_event.id);
            }
        }
    }

    fn handle_keyboard_input(&mut self, event: winit::event::KeyEvent) {
        debug!("Keyboard input: {event:?}");
        self.keyboard_state.push_event(event);
    }

    fn handle_redraw_requested(
        &mut self,
        #[cfg(target_os = "android")] event_loop: &ActiveEventLoop,
    ) {
        self.redraw_request_pending.store(false, Ordering::Release);
        let mut app = match self.app.take() {
            Some(app) => app,
            None => return,
        };

        app.resize_if_needed();
        let accessibility_enabled = self.accessibility_adapter.is_some();
        let frame_idx = self.frame_index;
        #[cfg(feature = "profiling")]
        let redraw_reasons = self.take_pending_redraw_reasons();
        let window_label = &self.config.window_title;

        let RenderFrameOutcome {
            accessibility_update,
            request_window_drag,
            runtime_pending_work,
            #[cfg(feature = "debug-dirty-overlay")]
            overlay_clear_pending,
        } = {
            let mut args = RenderFrameArgs {
                cursor_state: &mut self.cursor_state,
                keyboard_state: &mut self.keyboard_state,
                ime_state: &mut self.ime_state,
                ime_bridge_state: &mut self.ime_bridge_state,
                #[cfg(target_os = "android")]
                android_ime_opened: &mut self.android_ime_opened,
                app: &mut app,
                #[cfg(target_os = "android")]
                event_loop,
            };
            Self::execute_render_frame(RenderFrameContext {
                entry_point: &self.entry_point,
                args: &mut args,
                accessibility_enabled,
                decorations: self.config.window.decorations,
                window_label,
                frame_idx,
                #[cfg(feature = "profiling")]
                redraw_reasons,
            })
        };

        if request_window_drag {
            self.apply_window_drag(app.window());
        }
        if let Some(action) = self.take_pending_desktop_window_action() {
            self.apply_desktop_window_action(app.window(), action);
        }

        self.frame_index = self.frame_index.wrapping_add(1);

        if let Some(tree_update) = accessibility_update {
            self.push_accessibility_update(tree_update);
        }

        self.app = Some(app);

        if runtime_pending_work.requires_redraw() {
            #[cfg(feature = "profiling")]
            self.request_redraw_with_reasons(
                WakeSource::Runtime,
                runtime_pending_work.redraw_reasons(),
            );
            #[cfg(not(feature = "profiling"))]
            self.request_redraw_now();
        }
        #[cfg(feature = "debug-dirty-overlay")]
        if overlay_clear_pending {
            self.request_redraw_now();
        }
    }
}

/// Implementation of winit's `ApplicationHandler` trait for the Tessera
/// renderer.
///
/// This implementation handles the application lifecycle events from winit,
/// including window creation, suspension/resumption, and various window events.
/// It bridges the gap between winit's event system and Tessera's
/// component-based UI framework.
impl<F: Fn()> ApplicationHandler<RendererUserEvent> for Renderer<F> {
    /// Called when the application is resumed or started.
    ///
    /// This method is responsible for:
    /// - Creating the application window with appropriate attributes
    /// - Initializing the WGPU context and surface
    /// - Registering rendering pipelines
    /// - Setting up the initial application state
    ///
    /// On desktop platforms, this is typically called once at startup.
    /// On mobile platforms (especially Android), this may be called multiple
    /// times as the app is suspended and resumed.
    ///
    /// ## Window Configuration
    ///
    /// The window is created with:
    /// - Title: "Tessera"
    /// - Transparency: Enabled (allows for transparent backgrounds)
    /// - Default size and position (platform-dependent)
    ///
    /// ## Pipeline Registration
    ///
    /// After WGPU initialization, render modules register pipelines through
    /// [`PipelineContext`]. This typically includes basic component pipelines
    /// and any custom shaders your application requires.
    #[tracing::instrument(level = "debug", skip(self, event_loop))]
    fn resumed(&mut self, event_loop: &ActiveEventLoop) {
        event_loop.set_control_flow(ControlFlow::Wait);
        #[cfg(feature = "profiling")]
        submit_runtime_meta(RuntimeMeta {
            kind: RuntimeEventKind::Resumed,
        });
        #[cfg(target_family = "wasm")]
        self.finish_web_initialization(event_loop, self.web_init_epoch);
        // Just return if the app is already created
        if self.app.is_some() {
            self.install_runtime_redraw_waker();
            #[cfg(feature = "profiling")]
            self.request_redraw_with_reasons(WakeSource::Lifecycle, vec![RedrawReason::Startup]);
            #[cfg(not(feature = "profiling"))]
            self.request_redraw_now();
            return;
        }
        #[cfg(target_family = "wasm")]
        if self.web_init_in_progress {
            return;
        }

        // Create a new window (initially hidden for AccessKit initialization)
        let window_attributes = Window::default_attributes()
            .with_title(&self.config.window_title)
            .with_decorations(self.config.window.decorations)
            .with_resizable(self.config.window.resizable)
            .with_transparent(self.config.window.transparent)
            .with_visible(false); // Hide initially for AccessKit
        #[cfg(target_family = "wasm")]
        let window_attributes = {
            use winit::platform::web::WindowAttributesExtWebSys;

            if let Some(canvas) = Self::resolve_web_canvas(&self.config) {
                window_attributes
                    .with_canvas(Some(canvas))
                    .with_append(false)
            } else {
                window_attributes.with_append(true)
            }
        };
        let window = match event_loop.create_window(window_attributes) {
            Ok(window) => Arc::new(window),
            Err(err) => {
                error!("Failed to create window: {err}");
                return;
            }
        };

        // Initialize AccessKit adapter BEFORE showing the window
        if let Some(proxy) = self.event_loop_proxy.clone() {
            self.accessibility_adapter = Some(AccessKitAdapter::with_event_loop_proxy(
                event_loop, &window, proxy,
            ));
        }

        // Now show the window after AccessKit is initialized
        window.set_visible(true);
        self.update_native_window_shape(&window);

        #[cfg(target_family = "wasm")]
        {
            self.begin_web_initialization(window);
            return;
        }

        #[cfg(not(target_family = "wasm"))]
        {
            let mut render_core = pollster::block_on(RenderCore::new(
                window.clone(),
                self.config.sample_count,
                self.config.window.transparent,
            ));

            // Register pipelines
            let mut context = PipelineContext::new(&mut render_core);
            for module in &self.modules {
                module.register_pipelines(&mut context);
            }

            self.app = Some(render_core);
            self.install_runtime_redraw_waker();
            #[cfg(feature = "profiling")]
            self.request_redraw_with_reasons(WakeSource::Lifecycle, vec![RedrawReason::Startup]);
            #[cfg(not(feature = "profiling"))]
            self.request_redraw_now();

            if let Some(context) = self.plugin_context(event_loop) {
                self.plugins.resumed(&context);
            }
        }
    }

    /// Called when the application is suspended.
    ///
    /// This method should handle cleanup and state preservation when the
    /// application is being suspended (e.g., on mobile platforms when the
    /// app goes to background).
    ///
    /// ## Platform Considerations
    ///
    /// - **Desktop**: Rarely called, mainly during shutdown
    /// - **Android**: Called when app goes to background
    /// - **iOS**: Called during app lifecycle transitions
    fn suspended(&mut self, event_loop: &ActiveEventLoop) {
        debug!("Suspending renderer; tearing down WGPU resources.");
        #[cfg(feature = "profiling")]
        submit_runtime_meta(RuntimeMeta {
            kind: RuntimeEventKind::Suspended,
        });

        if let Some(context) = self.plugin_context(event_loop) {
            self.plugins.suspended(&context);
        }

        if let Some(mut app) = self.app.take() {
            app.compute_resource_manager_mut().clear();
        }

        // Clean up AccessKit adapter
        self.accessibility_adapter = None;

        self.cursor_state = CursorState::default();
        self.keyboard_state = KeyboardState::default();
        self.ime_state = ImeState::default();
        self.ime_bridge_state.reset();
        self.resize_in_progress = false;
        self.redraw_request_pending.store(false, Ordering::Release);
        #[cfg(target_family = "wasm")]
        {
            self.web_init_epoch = self.web_init_epoch.wrapping_add(1);
            self.web_init_in_progress = false;
            self.pending_web_inits.borrow_mut().clear();
        }
        #[cfg(target_os = "android")]
        {
            self.android_ime_opened = false;
        }

        TesseraRuntime::with_mut(|runtime| {
            runtime.component_tree.reset();
            runtime.cursor_icon_request = None;
            runtime.window_minimized = false;
            runtime.window_size = [0, 0];
        });
        clear_layout_snapshots();
        reset_layout_dirty_tracking();
        reset_component_replay_tracking();
        reset_focus_read_dependencies();
        reset_render_slot_read_dependencies();
        reset_state_read_dependencies();
        reset_component_context_tracking();
        reset_context_read_dependencies();
        reset_build_invalidations();
        reset_frame_clock();
        clear_redraw_waker();
        clear_persistent_focus_handles();
        crate::runtime::reset_slots();
        #[cfg(feature = "profiling")]
        self.pending_redraw_reasons.clear();
    }

    #[tracing::instrument(level = "debug", skip(self, event_loop))]
    fn window_event(
        &mut self,
        event_loop: &ActiveEventLoop,
        _window_id: WindowId,
        event: WindowEvent,
    ) {
        if self.pending_close_requested {
            self.pending_close_requested = false;
            self.handle_close_requested(event_loop);
            return;
        }

        // Forward event to AccessKit adapter
        if let (Some(adapter), Some(app)) = (&mut self.accessibility_adapter, &self.app) {
            adapter.process_event(app.window(), &event);
        }

        // Handle window events
        let mut request_redraw = false;
        #[cfg(feature = "profiling")]
        let mut redraw_reasons = Vec::new();
        match event {
            WindowEvent::CloseRequested => {
                self.handle_close_requested(event_loop);
            }
            WindowEvent::Resized(size) => {
                self.handle_resized(size);
                request_redraw = true;
                #[cfg(feature = "profiling")]
                redraw_reasons.push(RedrawReason::WindowResized);
            }
            WindowEvent::CursorMoved {
                device_id: _,
                position,
            } => {
                self.handle_cursor_moved(position);
                request_redraw = true;
                #[cfg(feature = "profiling")]
                redraw_reasons.push(RedrawReason::CursorMoved);
            }
            WindowEvent::CursorLeft { device_id: _ } => {
                self.handle_cursor_left();
                request_redraw = true;
                #[cfg(feature = "profiling")]
                redraw_reasons.push(RedrawReason::CursorLeft);
            }
            WindowEvent::MouseInput {
                device_id: _,
                state,
                button,
            } => {
                self.handle_mouse_input(state, button);
                request_redraw = true;
                #[cfg(feature = "profiling")]
                redraw_reasons.push(RedrawReason::MouseInput);
            }
            WindowEvent::MouseWheel {
                device_id: _,
                delta,
                phase: _,
            } => {
                self.handle_mouse_wheel(delta);
                request_redraw = true;
                #[cfg(feature = "profiling")]
                redraw_reasons.push(RedrawReason::MouseWheel);
            }
            WindowEvent::Touch(touch_event) => {
                self.handle_touch(touch_event);
                request_redraw = true;
                #[cfg(feature = "profiling")]
                redraw_reasons.push(RedrawReason::TouchInput);
            }
            WindowEvent::ScaleFactorChanged { scale_factor, .. } => {
                if let Some(scale_factor_lock) = SCALE_FACTOR.get() {
                    *scale_factor_lock.write() = scale_factor;
                } else {
                    let _ = SCALE_FACTOR.set(RwLock::new(scale_factor));
                }
                if let Some(app) = self.app.as_ref() {
                    self.update_native_window_shape(app.window());
                }
                request_redraw = true;
                #[cfg(feature = "profiling")]
                redraw_reasons.push(RedrawReason::ScaleFactorChanged);
            }
            WindowEvent::KeyboardInput { event, .. } => {
                self.handle_keyboard_input(event);
                request_redraw = true;
                #[cfg(feature = "profiling")]
                redraw_reasons.push(RedrawReason::KeyboardInput);
            }
            WindowEvent::ModifiersChanged(modifiers) => {
                debug!("Modifiers changed: {modifiers:?}");
                self.keyboard_state.update_modifiers(modifiers.state());
                request_redraw = true;
                #[cfg(feature = "profiling")]
                redraw_reasons.push(RedrawReason::ModifiersChanged);
            }
            WindowEvent::Ime(ime_event) => {
                debug!("IME event: {ime_event:?}");
                self.ime_state.push_event(ime_event);
                request_redraw = true;
                #[cfg(feature = "profiling")]
                redraw_reasons.push(RedrawReason::ImeEvent);
            }
            WindowEvent::Focused(focused) => {
                TesseraRuntime::with_mut(|runtime| {
                    runtime
                        .component_tree
                        .focus_owner_mut()
                        .set_owner_focused(focused);
                });
                flush_pending_focus_callbacks();
                if self.resize_in_progress {
                    self.resize_in_progress = false;
                    self.cursor_state.clear();
                }
                request_redraw = true;
                #[cfg(feature = "profiling")]
                redraw_reasons.push(RedrawReason::FocusChanged);
            }
            WindowEvent::RedrawRequested => {
                #[cfg(target_os = "android")]
                self.handle_redraw_requested(event_loop);
                #[cfg(not(target_os = "android"))]
                self.handle_redraw_requested();
            }
            _ => (),
        }

        if request_redraw {
            #[cfg(feature = "profiling")]
            self.request_redraw_with_reasons(WakeSource::WindowEvent, redraw_reasons);
            #[cfg(not(feature = "profiling"))]
            self.request_redraw_now();
        }
    }

    fn user_event(&mut self, event_loop: &ActiveEventLoop, event: RendererUserEvent) {
        use accesskit_winit::WindowEvent as AccessKitWindowEvent;
        #[cfg(not(target_family = "wasm"))]
        let _ = event_loop;

        match event {
            RendererUserEvent::RuntimeRedrawWake => {
                #[cfg(feature = "profiling")]
                self.request_redraw_with_reasons(
                    WakeSource::Runtime,
                    vec![RedrawReason::RuntimeInvalidation],
                );
                #[cfg(not(feature = "profiling"))]
                self.request_redraw_now();
            }
            #[cfg(target_family = "wasm")]
            RendererUserEvent::WebInitReady(epoch) => {
                self.finish_web_initialization(event_loop, epoch);
            }
            RendererUserEvent::AccessKit(event) => {
                if self.accessibility_adapter.is_none() {
                    return;
                }
                match event.window_event {
                    AccessKitWindowEvent::InitialTreeRequested => {
                        self.send_accessibility_update();
                    }
                    AccessKitWindowEvent::ActionRequested(action_request) => {
                        // Dispatch action to the appropriate component handler
                        let handled = TesseraRuntime::with_mut(|runtime| {
                            let (tree, metadatas, focus_owner) =
                                runtime.component_tree.accessibility_dispatch_context();
                            crate::accessibility::dispatch_action(
                                tree,
                                metadatas,
                                focus_owner,
                                action_request,
                            )
                        });
                        flush_pending_focus_callbacks();

                        if !handled {
                            debug!("Action was not handled by any component");
                        }
                    }
                    AccessKitWindowEvent::AccessibilityDeactivated => {
                        debug!("AccessKit deactivated");
                    }
                }
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::{RendererImeBridgeState, RendererImeBridgeUpdate};
    use crate::{ImeRequest, Px, PxPosition, px::PxSize};

    fn positioned_request(
        position: PxPosition,
        size: PxSize,
        selection_range: Option<std::ops::Range<usize>>,
        composition_range: Option<std::ops::Range<usize>>,
    ) -> ImeRequest {
        let mut request = ImeRequest::new(size)
            .with_local_position(position)
            .with_selection_range(selection_range)
            .with_composition_range(composition_range);
        request.position = Some(position);
        request
    }

    #[test]
    fn ime_bridge_enables_and_updates_cursor_area_for_first_request() {
        let mut bridge = RendererImeBridgeState::default();
        let request = positioned_request(
            PxPosition::new(Px(12), Px(18)),
            PxSize::new(Px(7), Px(13)),
            Some(2..6),
            Some(3..5),
        );

        let update = bridge.update_request(Some(request.clone()));

        assert_eq!(
            update,
            RendererImeBridgeUpdate {
                allowed: Some(true),
                cursor_area: Some((PxPosition::new(Px(12), Px(18)), PxSize::new(Px(7), Px(13)))),
                request: Some(request.clone()),
                snapshot_changed: true,
            }
        );
        assert_eq!(bridge.request(), Some(&request));
    }

    #[test]
    fn ime_bridge_reuses_identical_request_without_window_updates() {
        let request = positioned_request(
            PxPosition::new(Px(12), Px(18)),
            PxSize::new(Px(7), Px(13)),
            Some(2..6),
            Some(3..5),
        );
        let mut bridge = RendererImeBridgeState::default();
        bridge.update_request(Some(request.clone()));

        let update = bridge.update_request(Some(request.clone()));

        assert_eq!(
            update,
            RendererImeBridgeUpdate {
                allowed: None,
                cursor_area: None,
                request: Some(request.clone()),
                snapshot_changed: false,
            }
        );
        assert_eq!(bridge.request(), Some(&request));
    }

    #[test]
    fn ime_bridge_preserves_selection_and_composition_changes_without_cursor_reapply() {
        let size = PxSize::new(Px(7), Px(13));
        let mut bridge = RendererImeBridgeState::default();
        bridge.update_request(Some(positioned_request(
            PxPosition::new(Px(12), Px(18)),
            size,
            Some(2..6),
            Some(3..5),
        )));
        let next_request = positioned_request(
            PxPosition::new(Px(12), Px(18)),
            size,
            Some(4..8),
            Some(5..7),
        );

        let update = bridge.update_request(Some(next_request.clone()));

        assert_eq!(update.allowed, None);
        assert_eq!(update.cursor_area, None);
        assert!(update.snapshot_changed);
        assert_eq!(bridge.request(), Some(&next_request));
    }

    #[test]
    fn ime_bridge_disables_and_clears_snapshot_when_request_is_removed() {
        let request = positioned_request(
            PxPosition::new(Px(12), Px(18)),
            PxSize::new(Px(7), Px(13)),
            Some(2..6),
            Some(3..5),
        );
        let mut bridge = RendererImeBridgeState::default();
        bridge.update_request(Some(request));

        let update = bridge.update_request(None);

        assert_eq!(
            update,
            RendererImeBridgeUpdate {
                allowed: Some(false),
                cursor_area: None,
                request: None,
                snapshot_changed: true,
            }
        );
        assert_eq!(bridge.request(), None);
    }
}

/// Shows the Android soft keyboard (virtual keyboard).
///
/// This function uses JNI to interact with the Android system to display the
/// soft keyboard. It's specifically designed for Android applications and
/// handles the complex JNI calls required to show the input method.
///
/// ## Parameters
///
/// - `show_implicit`: Whether to show the keyboard implicitly (without explicit
///   user action)
/// - `android_app`: Reference to the Android application context
///
/// ## Platform Support
///
/// This function is only available on Android (`target_os = "android"`). It
/// will not be compiled on other platforms.
///
/// ## Error Handling
///
/// The function includes comprehensive error handling for JNI operations. If
/// any JNI call fails, the function will return early without crashing the
/// application. Exception handling is also included to clear any Java
/// exceptions that might occur.
///
/// ## Implementation Notes
///
/// This implementation is based on the android-activity crate and follows the
/// pattern established in: https://github.com/rust-mobile/android-activity/pull/178
///
/// The function performs these steps:
/// 1. Get the Java VM and activity context
/// 2. Find the InputMethodManager system service
/// 3. Get the current window's decor view
/// 4. Call `showSoftInput` on the InputMethodManager
///
/// ## Usage
///
/// This function is typically called internally by the renderer when IME input
/// is requested. You generally don't need to call this directly in application
/// code.
// https://github.com/rust-mobile/android-activity/pull/178
#[cfg(target_os = "android")]
pub fn show_soft_input(show_implicit: bool, android_app: &AndroidApp) {
    let ctx = android_app;

    let jvm = unsafe { jni::JavaVM::from_raw(ctx.vm_as_ptr().cast()) }.unwrap();
    let na = unsafe { jni::objects::JObject::from_raw(ctx.activity_as_ptr().cast()) };

    let mut env = jvm.attach_current_thread().unwrap();
    if env.exception_check().unwrap() {
        return;
    }
    let class_ctxt = env.find_class("android/content/Context").unwrap();
    if env.exception_check().unwrap() {
        return;
    }
    let ims = env
        .get_static_field(class_ctxt, "INPUT_METHOD_SERVICE", "Ljava/lang/String;")
        .unwrap();
    if env.exception_check().unwrap() {
        return;
    }

    let im_manager = env
        .call_method(
            &na,
            "getSystemService",
            "(Ljava/lang/String;)Ljava/lang/Object;",
            &[(&ims).into()],
        )
        .unwrap()
        .l()
        .unwrap();
    if env.exception_check().unwrap() {
        return;
    }

    let jni_window = env
        .call_method(&na, "getWindow", "()Landroid/view/Window;", &[])
        .unwrap()
        .l()
        .unwrap();
    if env.exception_check().unwrap() {
        return;
    }
    let view = env
        .call_method(&jni_window, "getDecorView", "()Landroid/view/View;", &[])
        .unwrap()
        .l()
        .unwrap();
    if env.exception_check().unwrap() {
        return;
    }

    let _ = env.call_method(
        im_manager,
        "showSoftInput",
        "(Landroid/view/View;I)Z",
        &[
            jni::objects::JValue::Object(&view),
            if show_implicit {
                (ndk_sys::ANATIVEACTIVITY_SHOW_SOFT_INPUT_IMPLICIT as i32).into()
            } else {
                0i32.into()
            },
        ],
    );
    // showSoftInput can trigger exceptions if the keyboard is currently animating
    // open/closed
    if env.exception_check().unwrap() {
        let _ = env.exception_clear();
    }
}

/// Hides the Android soft keyboard (virtual keyboard).
///
/// This function uses JNI to interact with the Android system to hide the soft
/// keyboard. It's the counterpart to [`show_soft_input`] and handles the
/// complex JNI calls required to dismiss the input method.
///
/// ## Parameters
///
/// - `android_app`: Reference to the Android application context
///
/// ## Platform Support
///
/// This function is only available on Android (`target_os = "android"`). It
/// will not be compiled on other platforms.
///
/// ## Error Handling
///
/// Like [`show_soft_input`], this function includes comprehensive error
/// handling for JNI operations. If any step fails, the function returns early
/// without crashing. Java exceptions are also properly handled and cleared.
///
/// ## Implementation Details
///
/// The function performs these steps:
/// 1. Get the Java VM and activity context
/// 2. Find the InputMethodManager system service
/// 3. Get the current window and its decor view
/// 4. Get the window token from the decor view
/// 5. Call `hideSoftInputFromWindow` on the InputMethodManager
///
/// ## Usage
///
/// This function is typically called internally by the renderer when IME input
/// is no longer needed. You generally don't need to call this directly in
/// application code.
///
/// ## Relationship to show_soft_input
///
/// This function is designed to work in tandem with [`show_soft_input`]. The
/// renderer automatically manages the keyboard visibility based on IME requests
/// from components.
#[cfg(target_os = "android")]
pub fn hide_soft_input(android_app: &AndroidApp) {
    use jni::objects::JValue;

    let ctx = android_app;
    let jvm = match unsafe { jni::JavaVM::from_raw(ctx.vm_as_ptr().cast()) } {
        Ok(jvm) => jvm,
        Err(_) => return, // Early exit if failing to get the JVM
    };
    let activity = unsafe { jni::objects::JObject::from_raw(ctx.activity_as_ptr().cast()) };

    let mut env = match jvm.attach_current_thread() {
        Ok(env) => env,
        Err(_) => return,
    };

    // --- 1. Get the InputMethodManager ---
    // This part is the same as in show_soft_input.
    let class_ctxt = match env.find_class("android/content/Context") {
        Ok(c) => c,
        Err(_) => return,
    };
    let ims_field =
        match env.get_static_field(class_ctxt, "INPUT_METHOD_SERVICE", "Ljava/lang/String;") {
            Ok(f) => f,
            Err(_) => return,
        };
    let ims = match ims_field.l() {
        Ok(s) => s,
        Err(_) => return,
    };

    let im_manager = match env.call_method(
        &activity,
        "getSystemService",
        "(Ljava/lang/String;)Ljava/lang/Object;",
        &[(&ims).into()],
    ) {
        Ok(m) => match m.l() {
            Ok(im) => im,
            Err(_) => return,
        },
        Err(_) => return,
    };

    // --- 2. Get the current window's token ---
    // This is the key step that differs from show_soft_input.
    let window = match env.call_method(&activity, "getWindow", "()Landroid/view/Window;", &[]) {
        Ok(w) => match w.l() {
            Ok(win) => win,
            Err(_) => return,
        },
        Err(_) => return,
    };

    let decor_view = match env.call_method(&window, "getDecorView", "()Landroid/view/View;", &[]) {
        Ok(v) => match v.l() {
            Ok(view) => view,
            Err(_) => return,
        },
        Err(_) => return,
    };

    let window_token =
        match env.call_method(&decor_view, "getWindowToken", "()Landroid/os/IBinder;", &[]) {
            Ok(t) => match t.l() {
                Ok(token) => token,
                Err(_) => return,
            },
            Err(_) => return,
        };

    // --- 3. Call hideSoftInputFromWindow ---
    let _ = env.call_method(
        &im_manager,
        "hideSoftInputFromWindow",
        "(Landroid/os/IBinder;I)Z",
        &[
            JValue::Object(&window_token),
            JValue::Int(0), // flags, usually 0
        ],
    );

    // Hiding the keyboard can also cause exceptions, so we clear them.
    if env.exception_check().unwrap_or(false) {
        let _ = env.exception_clear();
    }
}