Skip to main content

sui_runtime/
lib.rs

1#![forbid(unsafe_code)]
2
3mod app;
4mod command;
5mod diagnostics;
6mod logo;
7mod overlay;
8mod reactive;
9mod widget;
10
11use std::{
12    collections::{BTreeSet, HashMap, HashSet, VecDeque},
13    sync::{
14        Arc,
15        atomic::{AtomicU64, Ordering},
16    },
17};
18
19use sui_core::{
20    AsyncWakeToken, Clipboard, ClipboardBackend, CustomEvent, DirtyRegion, DragEvent,
21    DragEventKind, DragOutcome, DragPayload, DragScopeId, DragSessionId, DropEffect, Error, Event,
22    FontHandle, ImageHandle, InvalidationKind, InvalidationRequest, InvalidationTarget, KeyState,
23    Point, PointerButton, PointerButtons, PointerEvent, PointerEventKind, Rect, Result,
24    SemanticsActionRequest, SemanticsEvent, SemanticsNode, Size, TimerToken, Vector, WakeEvent,
25    WidgetId, WindowEvent, WindowId,
26};
27use sui_layout::Constraints;
28use sui_scene::{
29    ImageRegistry, LayerCompositionMode, RegisteredImage, Scene, SceneCommand, SceneFrame,
30    SceneLayer, SceneLayerDescriptor, SceneLayerUpdate, SceneLayerUpdateKind,
31};
32use sui_text::{FontRegistry, RegisteredFont, TextLayoutHandle, TextSystem};
33use web_time::Instant;
34
35pub use app::{Application, EmbeddedSvgImageResource, WindowBuilder, WindowIcon};
36pub use command::{
37    Command, CommandController, CommandCtx, CommandDelivery, CommandKey, CommandSender,
38    CommandTarget,
39};
40use command::{CommandInvalidation, CommandListeners, QueuedCommand};
41pub use diagnostics::{
42    CacheMetrics, CacheMetricsDelta, CommandDispatchSample, FramePhase, FramePhaseSample,
43    InvalidationTraceSample, PresentationLatencyDiagnostics, ReactiveInvalidationSample,
44    RenderDiagnostics, RendererSubmissionDiagnostics, RetainedPacketHotspotDiagnostics,
45    RetainedPacketRebuildDiagnostics, SceneStatistics, SceneStatisticsDetailMode,
46    TextCacheDeltaDiagnostics, TextCacheDiagnostics, WidgetRebuildSample, WidgetTimingPhase,
47    WidgetTimingSample, WindowColorManagementMode, WindowDynamicRangeMode,
48    WindowOutputColorPrimaries, WindowPerformanceSnapshot, WindowPerformanceSummary,
49    WindowRenderOptions, WindowStemDarkening, WindowTextCoveragePolicy, WindowTextHinting,
50    WindowTextSubpixelOrder, WindowToneMappingMode, clear_window_performance_snapshot,
51    clear_window_performance_snapshots, clear_window_render_options,
52    publish_window_performance_snapshot, set_window_render_options,
53    set_window_scene_statistics_detail_mode, window_performance_snapshot,
54    window_performance_summary, window_performance_text_caches, window_render_options,
55    window_scene_statistics_detail_mode,
56};
57pub use logo::{DEFAULT_SUI_LOGO_SVG, default_sui_logo_image};
58pub use overlay::{
59    OVERLAY_DISMISS_REQUEST, OverlayDismissPolicy, OverlayDismissReason, OverlayDismissRequest,
60    OverlayFocusBehavior, OverlayInitialFocus, OverlayKind, OverlayManagerSnapshot,
61    OverlayModality, OverlayOptions, OverlaySnapshot, OverlayTraceKind, OverlayTraceSample,
62};
63use std::rc::Rc;
64pub use sui_core::{DpiInfo, SafeAreaInsets};
65pub use sui_layout::LayoutContext;
66use widget::MeasureScope;
67pub use widget::{
68    ArrangeCtx, EventCtx, EventPhase, FocusRestorePolicy, FocusScope, FocusScopeState,
69    KeyedChildren, KeyedReconcile, LayerOptions, MeasureCtx, PaintBoundaryMode, PaintCtx,
70    SemanticsCtx, SingleChild, StackHostOptions, StackOrderPolicy, StackSurfaceOptions, Widget,
71    WidgetChildren, WidgetDiagnostic, WidgetDiagnosticsCtx, WidgetDiagnosticsSnapshot, WidgetPod,
72    WidgetPodMutVisitor, WidgetPodVisitor,
73};
74use widget::{
75    BeginDragRequest, DragRequest, DropAcceptanceRequest, FocusRequest, PaintImageResource,
76    PointerCaptureRequest, WakeRequest,
77};
78
79/// Internal typed notification delivered to widgets whose observable
80/// dependencies changed.
81pub const REACTIVE_CHANGED: CommandKey<()> = CommandKey::new("sui.reactive.changed");
82
83type PaintOutput = (
84    Scene,
85    Vec<(ImageHandle, PaintImageResource)>,
86    HashMap<WidgetId, Rect>,
87    Vec<InvalidationRequest>,
88    Option<Rect>,
89);
90
91static NEXT_WINDOW_ID: AtomicU64 = AtomicU64::new(1);
92
93/// Legacy root-event kind. Platform wakes no longer synthesize this event; use
94/// [`CommandSender`] and window/application controllers instead.
95pub const EXTERNAL_WAKE_KIND: &str = "sui.external.wake";
96
97pub struct Runtime {
98    next_font_id: u64,
99    next_image_id: u64,
100    font_registry: Arc<FontRegistry>,
101    image_registry: Arc<ImageRegistry>,
102    text_system: Arc<TextSystem>,
103    clipboard: Clipboard,
104    windows: Vec<WindowState>,
105    external_waker: Option<Arc<dyn Fn() + Send + Sync>>,
106    command_sender: CommandSender,
107    command_listeners: CommandListeners,
108}
109
110impl Runtime {
111    pub fn new() -> Self {
112        Self::with_registries(
113            1,
114            Arc::new(FontRegistry::new()),
115            1,
116            Arc::new(ImageRegistry::new()),
117        )
118    }
119
120    fn with_registries(
121        next_font_id: u64,
122        font_registry: Arc<FontRegistry>,
123        next_image_id: u64,
124        image_registry: Arc<ImageRegistry>,
125    ) -> Self {
126        Self {
127            next_font_id: next_font_id.max(1),
128            next_image_id: next_image_id.max(1),
129            font_registry,
130            image_registry,
131            text_system: Arc::new(TextSystem::new()),
132            clipboard: Clipboard::new(),
133            windows: Vec::new(),
134            external_waker: None,
135            command_sender: CommandSender::new(),
136            command_listeners: CommandListeners::default(),
137        }
138    }
139
140    pub fn add_window(&mut self, builder: WindowBuilder) -> Result<WindowId> {
141        let window_id = self.alloc_window_id();
142        let mut window = builder.build(window_id, self.command_sender.clone())?;
143        window.clipboard = self.clipboard.clone();
144        window.reactive_hub.set_waker(self.external_waker.clone());
145        self.windows.push(window);
146        Ok(window_id)
147    }
148
149    /// Install the platform callback used to wake the UI after an observable
150    /// invalidates one or more subscribed widgets.
151    pub fn set_external_waker(&mut self, waker: impl Fn() + Send + Sync + 'static) {
152        let waker: Arc<dyn Fn() + Send + Sync> = Arc::new(waker);
153        self.external_waker = Some(Arc::clone(&waker));
154        for window in &self.windows {
155            window.reactive_hub.set_waker(Some(Arc::clone(&waker)));
156        }
157    }
158
159    /// Install the platform callback used by the thread-safe command producer.
160    pub fn set_command_waker(&self, waker: impl Fn() + Send + Sync + 'static) {
161        self.command_sender.set_waker(Some(Arc::new(waker)));
162    }
163
164    /// Return the cloneable command producer associated with this runtime.
165    pub fn command_sender(&self) -> CommandSender {
166        self.command_sender.clone()
167    }
168
169    pub fn has_pending_commands(&self) -> bool {
170        self.command_sender.has_pending()
171    }
172
173    /// Drain observable changes into targeted widget invalidations without
174    /// delivering an application-level external wake event.
175    ///
176    /// Platform integrations call this after their reactive wake signal.
177    pub fn process_reactive_updates(&mut self) {
178        for window in &mut self.windows {
179            window.drain_reactive_invalidations();
180        }
181    }
182
183    /// Drain queued commands and scheduler-only wakes on the UI thread.
184    ///
185    /// Platform integrations call this in response to the command producer's
186    /// waker. Delivery is independent of hit testing and widget ancestry.
187    pub fn process_commands(&mut self) {
188        const MAX_COMMAND_ROUNDS: usize = 8;
189
190        for _ in 0..MAX_COMMAND_ROUNDS {
191            let (manual_wake, commands) = self.command_sender.drain();
192            if !manual_wake && commands.is_empty() {
193                break;
194            }
195            if manual_wake {
196                self.dispatch_controller_wake();
197            }
198            for command in commands {
199                self.dispatch_queued_command(&command);
200            }
201        }
202    }
203
204    /// Enqueue and synchronously drain a command. Intended for headless hosts
205    /// and tests that own the runtime loop directly.
206    pub fn handle_command<T>(
207        &mut self,
208        target: CommandTarget,
209        delivery: CommandDelivery,
210        key: CommandKey<T>,
211        payload: T,
212    ) where
213        T: Send + Sync + 'static,
214    {
215        match delivery {
216            CommandDelivery::Directed => self.command_sender.send(target, key, payload),
217            CommandDelivery::Broadcast => self.command_sender.broadcast(target, key, payload),
218        }
219        self.process_commands();
220    }
221
222    /// Shared clipboard handle used by every window in this runtime.
223    pub fn clipboard(&self) -> Clipboard {
224        self.clipboard.clone()
225    }
226
227    /// Install a clipboard storage driver (for example an OS-clipboard bridge
228    /// provided by the platform). Existing windows pick it up immediately.
229    pub fn set_clipboard_backend(&self, backend: impl ClipboardBackend + 'static) {
230        self.clipboard.set_backend(backend);
231    }
232
233    pub fn remove_window(&mut self, window_id: WindowId) -> Result<()> {
234        let Some(window_index) = self
235            .windows
236            .iter()
237            .position(|window| window.id == window_id)
238        else {
239            return Err(Error::new(format!(
240                "window {} does not exist",
241                window_id.get()
242            )));
243        };
244
245        self.windows.remove(window_index);
246        clear_window_performance_snapshot(window_id);
247        Ok(())
248    }
249
250    pub fn handle_event(&mut self, window_id: WindowId, event: Event) -> Result<()> {
251        self.dispatch_event(window_id, event).map(|_| ())
252    }
253
254    /// Dispatch an event and report whether widget routing or a built-in runtime behavior
255    /// consumed it.
256    ///
257    /// Platform hosts can use this to provide native fallbacks only when application and
258    /// runtime behavior did not handle an event. Most callers should continue to use
259    /// [`Runtime::handle_event`] when the dispatch outcome is not relevant.
260    pub fn dispatch_event(&mut self, window_id: WindowId, event: Event) -> Result<bool> {
261        let text_system = Arc::clone(&self.text_system);
262        let font_registry = Arc::clone(&self.font_registry);
263        let image_registry = Arc::clone(&self.image_registry);
264        let window = self.window_mut(window_id)?;
265        window.drain_reactive_invalidations();
266        let handled = window.handle_event(event, text_system, font_registry, image_registry);
267        window.drain_reactive_invalidations();
268        Ok(handled)
269    }
270
271    /// Invoke an action advertised by a node in the latest semantic snapshot.
272    ///
273    /// The semantic node does not need to be a retained [`WidgetPod`]. Virtual
274    /// and generated nodes are routed to their nearest graph-backed semantic
275    /// ancestor while [`SemanticsEvent::target`] preserves the original node
276    /// identity for widget-local dispatch. The return value is `false` when the
277    /// node is stale, hidden, disabled, does not advertise the action, or no
278    /// widget handles an action without a built-in runtime fallback.
279    pub fn handle_semantics_action(
280        &mut self,
281        window_id: WindowId,
282        target: WidgetId,
283        action: SemanticsActionRequest,
284    ) -> Result<bool> {
285        let text_system = Arc::clone(&self.text_system);
286        let font_registry = Arc::clone(&self.font_registry);
287        let image_registry = Arc::clone(&self.image_registry);
288        let window = self.window_mut(window_id)?;
289        Ok(window.handle_semantics_action(
290            target,
291            action,
292            text_system,
293            font_registry,
294            image_registry,
295        ))
296    }
297
298    pub fn tick(&mut self, frame_time: f64) {
299        for window in &mut self.windows {
300            window.last_tick_time = frame_time;
301        }
302    }
303
304    pub fn drain_ready_events(&mut self) -> Vec<(WindowId, Event)> {
305        let mut ready = Vec::new();
306
307        for window in &mut self.windows {
308            let window_id = window.id;
309            ready.extend(
310                window
311                    .drain_ready_events()
312                    .into_iter()
313                    .map(|event| (window_id, event)),
314            );
315        }
316
317        ready
318    }
319
320    pub fn next_wakeup_time(&self, window_id: WindowId) -> Result<Option<f64>> {
321        let window = self.window(window_id)?;
322        Ok(window.next_wakeup_time())
323    }
324
325    pub fn wake_async(&mut self, window_id: WindowId, token: AsyncWakeToken) -> Result<bool> {
326        let window = self.window_mut(window_id)?;
327        Ok(window.wake_async(token))
328    }
329
330    /// Explicitly deliver the legacy external-wake [`Event::Custom`] (kind
331    /// [`EXTERNAL_WAKE_KIND`]) to a window's root widget.
332    ///
333    /// Platform wakes do not call this method. New integrations should enqueue a
334    /// typed command or use [`CommandSender::wake`] with a controller.
335    pub fn wake_root(&mut self, window_id: WindowId) -> Result<()> {
336        self.handle_event(
337            window_id,
338            Event::Custom(CustomEvent::new(EXTERNAL_WAKE_KIND)),
339        )
340    }
341
342    pub fn register_font(&mut self, handle: FontHandle, font: RegisteredFont) -> Result<()> {
343        if Arc::make_mut(&mut self.font_registry)
344            .insert(handle, font)
345            .is_some()
346        {
347            return Err(Error::new(format!(
348                "font handle {} is already registered",
349                handle.get()
350            )));
351        }
352
353        self.next_font_id = self.next_font_id.max(handle.get() + 1);
354        Ok(())
355    }
356
357    pub fn register_font_bytes(&mut self, data: impl Into<Vec<u8>>) -> Result<FontHandle> {
358        let handle = FontHandle::new(self.next_font_id.max(1));
359        self.next_font_id = handle.get() + 1;
360        self.register_font(handle, RegisteredFont::from_bytes(data))?;
361        Ok(handle)
362    }
363
364    pub fn register_image(&mut self, handle: ImageHandle, image: RegisteredImage) -> Result<()> {
365        if Arc::make_mut(&mut self.image_registry)
366            .insert(handle, image)
367            .is_some()
368        {
369            return Err(Error::new(format!(
370                "image handle {} is already registered",
371                handle.get()
372            )));
373        }
374
375        self.next_image_id = self.next_image_id.max(handle.get() + 1);
376        Ok(())
377    }
378
379    pub fn register_svg_image_with_handle(
380        &mut self,
381        handle: ImageHandle,
382        data: impl AsRef<[u8]>,
383    ) -> Result<()> {
384        self.register_image(handle, RegisteredImage::from_svg(data)?)
385    }
386
387    pub fn register_rgba_image(
388        &mut self,
389        width: u32,
390        height: u32,
391        data: impl Into<Vec<u8>>,
392    ) -> Result<ImageHandle> {
393        let handle = ImageHandle::new(self.next_image_id.max(1));
394        self.next_image_id = handle.get() + 1;
395        self.register_image(handle, RegisteredImage::from_rgba8(width, height, data)?)?;
396        Ok(handle)
397    }
398
399    pub fn register_svg_image(&mut self, data: impl AsRef<[u8]>) -> Result<ImageHandle> {
400        let handle = ImageHandle::new(self.next_image_id.max(1));
401        self.next_image_id = handle.get() + 1;
402        self.register_image(handle, RegisteredImage::from_svg(data)?)?;
403        Ok(handle)
404    }
405
406    pub fn register_svg_image_at_size_with_handle(
407        &mut self,
408        handle: ImageHandle,
409        width: u32,
410        height: u32,
411        data: impl AsRef<[u8]>,
412    ) -> Result<()> {
413        self.register_image(
414            handle,
415            RegisteredImage::from_svg_at_size(width, height, data)?,
416        )
417    }
418
419    pub fn register_svg_image_at_size(
420        &mut self,
421        width: u32,
422        height: u32,
423        data: impl AsRef<[u8]>,
424    ) -> Result<ImageHandle> {
425        let handle = ImageHandle::new(self.next_image_id.max(1));
426        self.next_image_id = handle.get() + 1;
427        self.register_image(
428            handle,
429            RegisteredImage::from_svg_at_size(width, height, data)?,
430        )?;
431        Ok(handle)
432    }
433
434    pub fn register_embedded_svg_image(
435        &mut self,
436        resource: EmbeddedSvgImageResource,
437    ) -> Result<()> {
438        self.register_image(resource.handle(), resource.registered_image()?)
439    }
440
441    pub fn register_embedded_svg_images(
442        &mut self,
443        resources: impl IntoIterator<Item = EmbeddedSvgImageResource>,
444    ) -> Result<()> {
445        for resource in resources {
446            self.register_embedded_svg_image(resource)?;
447        }
448        Ok(())
449    }
450
451    pub fn font_registry(&self) -> &Arc<FontRegistry> {
452        &self.font_registry
453    }
454
455    pub fn image_registry(&self) -> &Arc<ImageRegistry> {
456        &self.image_registry
457    }
458
459    pub fn render(&mut self, window_id: WindowId) -> Result<RenderOutput> {
460        let text_system = Arc::clone(&self.text_system);
461        let font_registry = Arc::clone(&self.font_registry);
462        let image_registry = Arc::clone(&self.image_registry);
463        let window = self.window_mut(window_id)?;
464        window.drain_reactive_invalidations();
465        Ok(window.render(text_system, font_registry, image_registry))
466    }
467
468    pub fn semantics(&self, window_id: WindowId) -> Result<&[SemanticsNode]> {
469        let window = self.window(window_id)?;
470        Ok(&window.last_semantics)
471    }
472
473    pub fn window_title(&self, window_id: WindowId) -> Result<&str> {
474        let window = self.window(window_id)?;
475        Ok(&window.title)
476    }
477
478    pub fn window_icon(&self, window_id: WindowId) -> Result<Option<&WindowIcon>> {
479        let window = self.window(window_id)?;
480        Ok(window.icon.as_ref())
481    }
482
483    pub fn window_ids(&self) -> Vec<WindowId> {
484        self.windows.iter().map(|window| window.id).collect()
485    }
486
487    pub fn needs_render(&self, window_id: WindowId) -> Result<bool> {
488        let window = self.window(window_id)?;
489        Ok(window.needs_render())
490    }
491
492    pub fn schedule(&self, window_id: WindowId) -> Result<FrameSchedule> {
493        let window = self.window(window_id)?;
494        Ok(window.schedule)
495    }
496
497    pub fn focus_state(&self, window_id: WindowId) -> Result<FocusState> {
498        let window = self.window(window_id)?;
499        Ok(window.focus)
500    }
501
502    pub fn focused_widget(&self, window_id: WindowId) -> Result<Option<WidgetId>> {
503        Ok(self.focus_state(window_id)?.focused_widget)
504    }
505
506    pub fn pointer_capture_target(
507        &self,
508        window_id: WindowId,
509        pointer_id: u64,
510    ) -> Result<Option<WidgetId>> {
511        let window = self.window(window_id)?;
512        Ok(window.pointer_capture.get(&pointer_id).copied())
513    }
514
515    pub fn widget_graph(&self, window_id: WindowId) -> Result<WidgetGraphSnapshot> {
516        let window = self.window(window_id)?;
517        Ok(window.graph.snapshot())
518    }
519
520    /// Enable or disable bounded route and invalidation history for a window.
521    /// Structural snapshots remain available while tracing is disabled.
522    pub fn set_inspector_tracing(&mut self, window_id: WindowId, enabled: bool) -> Result<()> {
523        let window = self.window_mut(window_id)?;
524        if window.inspector_tracing_enabled != enabled {
525            window.clear_inspector_history();
526            window.last_render_diagnostics = RenderDiagnostics::default();
527        }
528        window.inspector_tracing_enabled = enabled;
529        Ok(())
530    }
531
532    pub fn inspector_tracing(&self, window_id: WindowId) -> Result<bool> {
533        Ok(self.window(window_id)?.inspector_tracing_enabled)
534    }
535
536    /// Capture a unified renderer-neutral snapshot for debug tooling.
537    pub fn inspector_snapshot(&self, window_id: WindowId) -> Result<WindowInspectorSnapshot> {
538        let window = self.window(window_id)?;
539        Ok(window.inspector_snapshot())
540    }
541
542    /// Inspect the window's currently presented overlay stack.
543    pub fn overlay_snapshot(&self, window_id: WindowId) -> Result<OverlayManagerSnapshot> {
544        let window = self.window(window_id)?;
545        Ok(window.overlay_manager.snapshot())
546    }
547
548    /// Drain overlay lifecycle and dismissal diagnostics for an inspector.
549    pub fn take_overlay_traces(&mut self, window_id: WindowId) -> Result<Vec<OverlayTraceSample>> {
550        let window = self.window_mut(window_id)?;
551        Ok(window.overlay_manager.take_traces())
552    }
553
554    fn dispatch_controller_wake(&mut self) {
555        let sender = self.command_sender.clone();
556        let mut app_ctx = CommandCtx::new(sender.clone(), None);
557        let app_handlers = self.command_listeners.wake(&mut app_ctx);
558        self.apply_command_ctx(
559            app_ctx,
560            "scheduler wake",
561            "()",
562            None,
563            0,
564            CommandTarget::Application,
565            CommandDelivery::Broadcast,
566            app_handlers,
567        );
568
569        for index in 0..self.windows.len() {
570            let window_id = self.windows[index].id;
571            let mut ctx = CommandCtx::new(sender.clone(), Some(window_id));
572            let handlers = self.windows[index].command_listeners.wake(&mut ctx);
573            self.apply_command_ctx(
574                ctx,
575                "scheduler wake",
576                "()",
577                Some(index),
578                0,
579                CommandTarget::Window(window_id),
580                CommandDelivery::Broadcast,
581                handlers,
582            );
583        }
584    }
585
586    fn dispatch_queued_command(&mut self, queued: &QueuedCommand) {
587        match queued.target {
588            CommandTarget::Widget {
589                window_id,
590                widget_id,
591            } => {
592                if let Some(index) = self
593                    .windows
594                    .iter()
595                    .position(|window| window.id == window_id)
596                {
597                    let Some(dispatch) =
598                        self.windows[index].dispatch_direct_command(widget_id, queued)
599                    else {
600                        push_trace(
601                            &mut self.windows[index].pending_command_diagnostics,
602                            command_sample(queued, Vec::new(), false, false),
603                        );
604                        return;
605                    };
606                    let (handlers, handled) = {
607                        let handled = dispatch.handled;
608                        (vec!["widget target".to_string()], handled)
609                    };
610                    let focus_request = dispatch.focus_request;
611                    let mut effects = EventEffects::default();
612                    effects.extend(dispatch);
613                    let mut invalidations = Vec::new();
614                    self.windows[index].apply_event_effects(effects, &mut invalidations);
615                    if let Some(request) = focus_request {
616                        let focus_effects = self.windows[index].apply_focus_request(request);
617                        self.windows[index].apply_event_effects(focus_effects, &mut invalidations);
618                    }
619                    self.windows[index].record_command_invalidations(
620                        &invalidations,
621                        queued.key.name,
622                        None,
623                    );
624                    self.windows[index].schedule.extend(&invalidations);
625                    self.windows[index]
626                        .pending_invalidations
627                        .extend(invalidations);
628                    push_trace(
629                        &mut self.windows[index].pending_command_diagnostics,
630                        command_sample(queued, handlers, handled, true),
631                    );
632                }
633            }
634            CommandTarget::FocusedWidget(window_id) => {
635                if let Some(index) = self
636                    .windows
637                    .iter()
638                    .position(|window| window.id == window_id)
639                {
640                    let Some(target) = self.windows[index].focus.focused_widget else {
641                        push_trace(
642                            &mut self.windows[index].pending_command_diagnostics,
643                            command_sample(queued, Vec::new(), false, false),
644                        );
645                        return;
646                    };
647                    let Some(dispatch) =
648                        self.windows[index].dispatch_direct_command(target, queued)
649                    else {
650                        push_trace(
651                            &mut self.windows[index].pending_command_diagnostics,
652                            command_sample(queued, Vec::new(), false, false),
653                        );
654                        return;
655                    };
656                    let handled = { dispatch.handled };
657                    let focus_request = dispatch.focus_request;
658                    let mut effects = EventEffects::default();
659                    effects.extend(dispatch);
660                    let mut invalidations = Vec::new();
661                    self.windows[index].apply_event_effects(effects, &mut invalidations);
662                    if let Some(request) = focus_request {
663                        let focus_effects = self.windows[index].apply_focus_request(request);
664                        self.windows[index].apply_event_effects(focus_effects, &mut invalidations);
665                    }
666                    self.windows[index].record_command_invalidations(
667                        &invalidations,
668                        queued.key.name,
669                        None,
670                    );
671                    self.windows[index].schedule.extend(&invalidations);
672                    self.windows[index]
673                        .pending_invalidations
674                        .extend(invalidations);
675                    push_trace(
676                        &mut self.windows[index].pending_command_diagnostics,
677                        command_sample(queued, vec!["focused widget".to_string()], handled, true),
678                    );
679                }
680            }
681            CommandTarget::Window(window_id) => {
682                if let Some(index) = self
683                    .windows
684                    .iter()
685                    .position(|window| window.id == window_id)
686                {
687                    self.dispatch_to_window_listeners(index, queued);
688                }
689            }
690            CommandTarget::Application => {
691                let sender = self.command_sender.clone();
692                let mut ctx = CommandCtx::new(sender.clone(), None);
693                let broadcast = queued.delivery == CommandDelivery::Broadcast;
694                let command = Command::new(queued);
695                let handlers = self
696                    .command_listeners
697                    .dispatch(&mut ctx, &command, broadcast);
698                self.apply_command_ctx(
699                    ctx,
700                    queued.key.name,
701                    queued.key.payload_type_name,
702                    None,
703                    queued.sequence,
704                    queued.target,
705                    queued.delivery,
706                    handlers,
707                );
708
709                if broadcast {
710                    for index in 0..self.windows.len() {
711                        self.dispatch_to_window_listeners(index, queued);
712                    }
713                }
714            }
715        }
716    }
717
718    fn dispatch_to_window_listeners(&mut self, index: usize, queued: &QueuedCommand) {
719        let sender = self.command_sender.clone();
720        let window_id = self.windows[index].id;
721        let mut ctx = CommandCtx::new(sender, Some(window_id));
722        let broadcast = queued.delivery == CommandDelivery::Broadcast;
723        let command = Command::new(queued);
724        let handlers = self.windows[index]
725            .command_listeners
726            .dispatch(&mut ctx, &command, broadcast);
727        self.apply_command_ctx(
728            ctx,
729            queued.key.name,
730            queued.key.payload_type_name,
731            Some(index),
732            queued.sequence,
733            queued.target,
734            queued.delivery,
735            handlers,
736        );
737    }
738
739    #[allow(clippy::too_many_arguments)]
740    fn apply_command_ctx(
741        &mut self,
742        mut ctx: CommandCtx,
743        source: &str,
744        payload_type: &str,
745        delivery_window: Option<usize>,
746        sequence: u64,
747        target: CommandTarget,
748        delivery: CommandDelivery,
749        handlers: Vec<String>,
750    ) {
751        let handled = ctx.is_handled();
752        let invalidations = ctx.take_invalidations();
753        let animations = ctx.take_animation_targets();
754        for invalidation in invalidations {
755            self.apply_command_invalidation(invalidation, source, delivery_window);
756        }
757        for (window_id, widget_id) in animations {
758            if let Some(window) = self
759                .windows
760                .iter_mut()
761                .find(|window| window.id == window_id)
762            {
763                window.requested_animation_frames.insert(widget_id);
764            }
765        }
766
767        let sample = CommandDispatchSample {
768            sequence,
769            name: source.to_string(),
770            payload_type: payload_type.to_string(),
771            target,
772            delivery,
773            delivered: !handlers.is_empty(),
774            handlers,
775            handled,
776        };
777        if let Some(index) = delivery_window {
778            push_trace(&mut self.windows[index].pending_command_diagnostics, sample);
779        } else {
780            for window in &mut self.windows {
781                push_trace(&mut window.pending_command_diagnostics, sample.clone());
782            }
783        }
784    }
785
786    fn apply_command_invalidation(
787        &mut self,
788        invalidation: CommandInvalidation,
789        source: &str,
790        delivery_window: Option<usize>,
791    ) {
792        let target_index = match invalidation.request.target {
793            InvalidationTarget::Window(window_id) => self
794                .windows
795                .iter()
796                .position(|window| window.id == window_id),
797            InvalidationTarget::Widget(widget_id) => self.windows.iter().position(|window| {
798                window.root.id() == widget_id || window.graph.contains(widget_id)
799            }),
800            InvalidationTarget::Surface(_) => delivery_window,
801        };
802        let Some(index) = target_index else {
803            return;
804        };
805        let request = invalidation.request;
806        push_trace(
807            &mut self.windows[index].pending_invalidation_diagnostics,
808            InvalidationTraceSample {
809                target: request.target,
810                kind: request.kind,
811                region: request.region,
812                source: format!("command:{source}"),
813                reason: invalidation.reason,
814            },
815        );
816        self.windows[index]
817            .schedule
818            .extend(std::slice::from_ref(&request));
819        self.windows[index].pending_invalidations.push(request);
820    }
821
822    fn alloc_window_id(&mut self) -> WindowId {
823        WindowId::new(NEXT_WINDOW_ID.fetch_add(1, Ordering::Relaxed))
824    }
825
826    fn window(&self, window_id: WindowId) -> Result<&WindowState> {
827        self.windows
828            .iter()
829            .find(|window| window.id == window_id)
830            .ok_or_else(|| Error::new(format!("window {} does not exist", window_id.get())))
831    }
832
833    fn window_mut(&mut self, window_id: WindowId) -> Result<&mut WindowState> {
834        self.windows
835            .iter_mut()
836            .find(|window| window.id == window_id)
837            .ok_or_else(|| Error::new(format!("window {} does not exist", window_id.get())))
838    }
839}
840
841impl Default for Runtime {
842    fn default() -> Self {
843        Self::new()
844    }
845}
846
847#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
848pub struct FocusState {
849    pub focused_widget: Option<WidgetId>,
850    pub window_focused: bool,
851}
852
853#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
854pub struct FrameSchedule {
855    pub measure: bool,
856    pub arrange: bool,
857    pub ordering: bool,
858    pub paint: bool,
859    pub semantics: bool,
860    pub hit_test: bool,
861    pub text: bool,
862    pub resources: bool,
863}
864
865impl FrameSchedule {
866    fn bootstrap() -> Self {
867        Self {
868            measure: true,
869            arrange: true,
870            ordering: false,
871            paint: true,
872            semantics: true,
873            hit_test: true,
874            text: false,
875            resources: false,
876        }
877    }
878
879    pub const fn any(self) -> bool {
880        self.measure
881            || self.arrange
882            || self.ordering
883            || self.paint
884            || self.semantics
885            || self.hit_test
886            || self.text
887            || self.resources
888    }
889
890    pub const fn needs_render(self) -> bool {
891        self.measure
892            || self.arrange
893            || self.ordering
894            || self.paint
895            || self.semantics
896            || self.text
897            || self.resources
898    }
899
900    fn clear(&mut self) {
901        *self = Self::default();
902    }
903
904    fn mark(&mut self, kind: InvalidationKind) {
905        match kind {
906            InvalidationKind::Measure => {
907                self.measure = true;
908                self.arrange = true;
909                self.ordering = true;
910                self.paint = true;
911                self.hit_test = true;
912                self.semantics = true;
913            }
914            InvalidationKind::Arrange
915            | InvalidationKind::Transform
916            | InvalidationKind::Clip
917            | InvalidationKind::Visibility => {
918                self.ordering = true;
919                self.arrange = true;
920                self.paint = true;
921                self.hit_test = true;
922                self.semantics = true;
923            }
924            InvalidationKind::Ordering => {
925                self.ordering = true;
926                self.hit_test = true;
927            }
928            InvalidationKind::Effect => {
929                self.paint = true;
930            }
931            InvalidationKind::Paint => {
932                self.paint = true;
933            }
934            InvalidationKind::HitTest => {
935                self.hit_test = true;
936            }
937            InvalidationKind::Text => {
938                self.text = true;
939                self.measure = true;
940                self.arrange = true;
941                self.paint = true;
942                self.semantics = true;
943            }
944            InvalidationKind::Semantics => {
945                self.semantics = true;
946            }
947            InvalidationKind::Resources => {
948                self.resources = true;
949                self.paint = true;
950            }
951        }
952    }
953
954    fn extend(&mut self, invalidations: &[InvalidationRequest]) {
955        for request in invalidations {
956            self.mark(request.kind);
957        }
958    }
959}
960
961#[derive(Debug, Clone, PartialEq)]
962pub struct WidgetGeometrySnapshot {
963    pub layout_bounds: Rect,
964    pub input_bounds: Rect,
965    pub paint_bounds: Rect,
966}
967
968impl WidgetGeometrySnapshot {
969    pub const fn new(layout_bounds: Rect, input_bounds: Rect, paint_bounds: Rect) -> Self {
970        Self {
971            layout_bounds,
972            input_bounds,
973            paint_bounds,
974        }
975    }
976}
977
978#[derive(Debug, Clone, PartialEq)]
979pub struct WidgetNodeSnapshot {
980    pub id: WidgetId,
981    pub widget_name: &'static str,
982    pub parent: Option<WidgetId>,
983    pub children: Vec<WidgetId>,
984    pub measured_size: Size,
985    pub geometry: WidgetGeometrySnapshot,
986    // Backward-compatible alias of geometry.layout_bounds.
987    pub bounds: Rect,
988    pub paint_boundary: PaintBoundaryMode,
989    pub stack_host: WidgetId,
990    pub stack_surface: WidgetId,
991    pub stack_surface_order: usize,
992    pub transient_owner_surface: Option<WidgetId>,
993    /// Logical overlay owner coordinating this node, when any.
994    pub overlay_owner: Option<WidgetId>,
995    pub is_overlay_owner: bool,
996    pub is_stack_host: bool,
997    pub is_stack_surface: bool,
998    pub hit_test: bool,
999    pub stack_order_policy: StackOrderPolicy,
1000    pub accepts_focus: bool,
1001    pub focused: bool,
1002}
1003
1004#[derive(Debug, Clone, PartialEq)]
1005pub struct StackHostSnapshot {
1006    pub host: WidgetId,
1007    pub order_policy: StackOrderPolicy,
1008    pub surfaces: Vec<WidgetId>,
1009}
1010
1011#[derive(Debug, Clone, PartialEq)]
1012pub struct WidgetGraphSnapshot {
1013    pub root: WidgetId,
1014    pub nodes: Vec<WidgetNodeSnapshot>,
1015    pub stack_hosts: Vec<StackHostSnapshot>,
1016}
1017
1018#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1019pub enum EventRoutePhase {
1020    Capture,
1021    Target,
1022    Bubble,
1023}
1024
1025#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1026pub struct EventRouteStep {
1027    pub widget_id: WidgetId,
1028    pub phase: EventRoutePhase,
1029    pub handled: bool,
1030}
1031
1032/// Privacy-safe event routing trace. Event payloads and typed characters are
1033/// intentionally not retained.
1034#[derive(Debug, Clone, PartialEq, Eq)]
1035pub struct EventRouteTraceSample {
1036    pub sequence: u64,
1037    pub event_kind: &'static str,
1038    pub target: WidgetId,
1039    pub path: Vec<WidgetId>,
1040    pub steps: Vec<EventRouteStep>,
1041    pub handled: bool,
1042}
1043
1044#[derive(Debug, Clone, Copy, PartialEq)]
1045pub struct TimerInspectorSnapshot {
1046    pub token: TimerToken,
1047    pub target: WidgetId,
1048    pub deadline: f64,
1049    pub delivering: bool,
1050}
1051
1052#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1053pub struct AsyncTaskInspectorSnapshot {
1054    pub token: AsyncWakeToken,
1055    pub target: WidgetId,
1056    pub pending_wake: bool,
1057}
1058
1059#[derive(Debug, Clone, PartialEq, Default)]
1060pub struct SchedulerInspectorSnapshot {
1061    pub timers: Vec<TimerInspectorSnapshot>,
1062    pub async_tasks: Vec<AsyncTaskInspectorSnapshot>,
1063    pub requested_animation_frames: Vec<WidgetId>,
1064    pub delivering_animation_frames: Vec<WidgetId>,
1065    pub last_animation_frame_time: Option<f64>,
1066}
1067
1068#[derive(Debug, Clone, PartialEq, Default)]
1069pub struct InspectorHistorySnapshot {
1070    pub event_routes: Vec<EventRouteTraceSample>,
1071    pub reactive_invalidations: Vec<ReactiveInvalidationSample>,
1072    pub command_dispatches: Vec<CommandDispatchSample>,
1073    pub invalidations: Vec<InvalidationTraceSample>,
1074    pub widget_rebuilds: Vec<WidgetRebuildSample>,
1075}
1076
1077/// Renderer-neutral, point-in-time state consumed by testing tools and live
1078/// inspector UIs. Capturing widget-specific diagnostics is opt-in and happens
1079/// only while this snapshot is requested.
1080#[derive(Debug, Clone, PartialEq)]
1081pub struct WindowInspectorSnapshot {
1082    pub window_id: WindowId,
1083    pub title: String,
1084    pub tracing_enabled: bool,
1085    pub focus_state: FocusState,
1086    pub schedule: FrameSchedule,
1087    pub semantics: Vec<SemanticsNode>,
1088    pub widget_graph: WidgetGraphSnapshot,
1089    pub overlays: OverlayManagerSnapshot,
1090    pub scheduler: SchedulerInspectorSnapshot,
1091    pub widget_diagnostics: Vec<WidgetDiagnosticsSnapshot>,
1092    pub last_render_diagnostics: RenderDiagnostics,
1093    pub history: InspectorHistorySnapshot,
1094    pub scene: Option<SceneStatistics>,
1095}
1096
1097#[derive(Debug, Clone, Copy, PartialEq)]
1098struct ScheduledTimer {
1099    token: TimerToken,
1100    deadline: f64,
1101    target: WidgetId,
1102}
1103
1104#[derive(Debug, Clone, Copy, PartialEq)]
1105struct LayerTranslation {
1106    widget_id: WidgetId,
1107    delta: Vector,
1108}
1109
1110#[derive(Debug, Clone, PartialEq)]
1111struct LayerDescriptorRefresh {
1112    widget_id: WidgetId,
1113    descriptor: SceneLayerDescriptor,
1114}
1115
1116#[derive(Debug, Default)]
1117struct GraphChangeSet {
1118    repaint_widgets: Vec<WidgetId>,
1119    transform_widgets: Vec<LayerTranslation>,
1120}
1121
1122const ANIMATION_FRAME_INTERVAL_SECONDS: f64 = 1.0 / 120.0;
1123
1124#[derive(Debug, Clone)]
1125struct ActiveDrag {
1126    session_id: DragSessionId,
1127    scope_id: DragScopeId,
1128    pointer_id: u64,
1129    source: WidgetId,
1130    start_position: Point,
1131    position: Point,
1132    payload: DragPayload,
1133    allowed_effect: DropEffect,
1134    preview_label: Option<Arc<str>>,
1135    hover_path: Vec<WidgetId>,
1136    accepted_target: Option<WidgetId>,
1137    accepted_effect: DropEffect,
1138}
1139
1140impl ActiveDrag {
1141    fn from_request(request: BeginDragRequest) -> Self {
1142        Self {
1143            session_id: request.session_id,
1144            scope_id: request.scope_id,
1145            pointer_id: request.pointer_id,
1146            source: request.source,
1147            start_position: request.position,
1148            position: request.position,
1149            payload: request.payload,
1150            allowed_effect: request.allowed_effect,
1151            preview_label: request.preview_label.map(Arc::from),
1152            hover_path: Vec::new(),
1153            accepted_target: None,
1154            accepted_effect: DropEffect::None,
1155        }
1156    }
1157
1158    fn event(
1159        &self,
1160        kind: DragEventKind,
1161        position: Point,
1162        target: Option<WidgetId>,
1163        accepted_effect: DropEffect,
1164        outcome: Option<DragOutcome>,
1165    ) -> Event {
1166        Event::Drag(DragEvent {
1167            kind,
1168            session_id: self.session_id,
1169            scope_id: self.scope_id,
1170            pointer_id: self.pointer_id,
1171            source: self.source,
1172            target,
1173            position,
1174            start_position: self.start_position,
1175            payload: self.payload.clone(),
1176            allowed_effect: self.allowed_effect,
1177            accepted_effect,
1178            preview_label: self.preview_label.clone(),
1179            outcome,
1180        })
1181    }
1182}
1183
1184struct WindowState {
1185    id: WindowId,
1186    title: String,
1187    icon: Option<WindowIcon>,
1188    root: WidgetPod,
1189    graph: WidgetGraph,
1190    overlay_manager: overlay::OverlayManager,
1191    pending_overlay_focus: Option<FocusRequest>,
1192    focus: FocusState,
1193    focused_semantics: Option<WidgetId>,
1194    schedule: FrameSchedule,
1195    scale_factor: f32,
1196    raw_dpi: Option<f32>,
1197    safe_area: SafeAreaInsets,
1198    viewport_hint: Option<Size>,
1199    viewport: Option<Size>,
1200    last_frame: Option<SceneFrame>,
1201    last_paint_bounds_by_widget: HashMap<WidgetId, Rect>,
1202    last_semantics: Vec<SemanticsNode>,
1203    pending_invalidations: Vec<InvalidationRequest>,
1204    pending_reactive_diagnostics: Vec<ReactiveInvalidationSample>,
1205    reactive_hub: Arc<reactive::ReactiveInvalidationHub>,
1206    pointer_capture: HashMap<u64, WidgetId>,
1207    last_pointer_events: HashMap<u64, PointerEvent>,
1208    pointer_hover_paths: HashMap<u64, Vec<WidgetId>>,
1209    active_drag: Option<ActiveDrag>,
1210    scheduled_timers: Vec<ScheduledTimer>,
1211    delivering_timers: HashMap<TimerToken, WidgetId>,
1212    async_wake_targets: HashMap<AsyncWakeToken, WidgetId>,
1213    pending_async_wakeups: VecDeque<AsyncWakeToken>,
1214    requested_animation_frames: BTreeSet<WidgetId>,
1215    delivering_animation_frames: VecDeque<WidgetId>,
1216    last_animation_frame_time: Option<f64>,
1217    next_animation_frame_index: u64,
1218    pending_animation_wake_count: usize,
1219    ime_composition_rect: Option<Rect>,
1220    last_tick_time: f64,
1221    clipboard: Clipboard,
1222    command_sender: CommandSender,
1223    command_listeners: CommandListeners,
1224    pending_command_diagnostics: Vec<CommandDispatchSample>,
1225    pending_invalidation_diagnostics: Vec<InvalidationTraceSample>,
1226    inspector_tracing_enabled: bool,
1227    next_event_route_sequence: u64,
1228    event_route_history: VecDeque<EventRouteTraceSample>,
1229    reactive_invalidation_history: VecDeque<ReactiveInvalidationSample>,
1230    command_dispatch_history: VecDeque<CommandDispatchSample>,
1231    invalidation_history: VecDeque<InvalidationTraceSample>,
1232    widget_rebuild_history: VecDeque<WidgetRebuildSample>,
1233    last_render_diagnostics: RenderDiagnostics,
1234}
1235
1236impl WindowState {
1237    fn new(
1238        id: WindowId,
1239        title: String,
1240        icon: Option<WindowIcon>,
1241        root: WidgetPod,
1242        command_listeners: CommandListeners,
1243        command_sender: CommandSender,
1244    ) -> Self {
1245        let focus = FocusState {
1246            focused_widget: None,
1247            window_focused: true,
1248        };
1249
1250        let reactive_hub = reactive::ReactiveInvalidationHub::new();
1251        reactive::register_window(id, &reactive_hub);
1252        Self {
1253            id,
1254            title,
1255            icon,
1256            graph: WidgetGraph::empty(root.id()),
1257            overlay_manager: overlay::OverlayManager::default(),
1258            pending_overlay_focus: None,
1259            root,
1260            focus,
1261            focused_semantics: None,
1262            schedule: FrameSchedule::bootstrap(),
1263            scale_factor: 1.0,
1264            raw_dpi: None,
1265            safe_area: SafeAreaInsets::ZERO,
1266            viewport_hint: None,
1267            viewport: None,
1268            last_frame: None,
1269            last_paint_bounds_by_widget: HashMap::new(),
1270            last_semantics: Vec::new(),
1271            pending_invalidations: Vec::new(),
1272            pending_reactive_diagnostics: Vec::new(),
1273            reactive_hub,
1274            pointer_capture: HashMap::new(),
1275            last_pointer_events: HashMap::new(),
1276            pointer_hover_paths: HashMap::new(),
1277            active_drag: None,
1278            scheduled_timers: Vec::new(),
1279            delivering_timers: HashMap::new(),
1280            async_wake_targets: HashMap::new(),
1281            pending_async_wakeups: VecDeque::new(),
1282            requested_animation_frames: BTreeSet::new(),
1283            delivering_animation_frames: VecDeque::new(),
1284            last_animation_frame_time: None,
1285            next_animation_frame_index: 0,
1286            pending_animation_wake_count: 0,
1287            ime_composition_rect: None,
1288            last_tick_time: 0.0,
1289            clipboard: Clipboard::new(),
1290            command_sender,
1291            command_listeners,
1292            pending_command_diagnostics: Vec::new(),
1293            pending_invalidation_diagnostics: Vec::new(),
1294            inspector_tracing_enabled: false,
1295            next_event_route_sequence: 0,
1296            event_route_history: VecDeque::new(),
1297            reactive_invalidation_history: VecDeque::new(),
1298            command_dispatch_history: VecDeque::new(),
1299            invalidation_history: VecDeque::new(),
1300            widget_rebuild_history: VecDeque::new(),
1301            last_render_diagnostics: RenderDiagnostics::default(),
1302        }
1303    }
1304
1305    fn drain_reactive_invalidations(&mut self) {
1306        const MAX_REACTIVE_ROUNDS: usize = 8;
1307
1308        for _ in 0..MAX_REACTIVE_ROUNDS {
1309            let pending = self.reactive_hub.drain();
1310            if pending.is_empty() {
1311                break;
1312            }
1313
1314            let mut invalidations = Vec::new();
1315            let mut targets = BTreeSet::new();
1316            for (request, mut sample) in pending {
1317                let InvalidationTarget::Widget(widget_id) = request.target else {
1318                    continue;
1319                };
1320                let delivered = self.graph.is_empty() || self.graph.contains(widget_id);
1321                sample.delivered = delivered;
1322                if delivered {
1323                    push_trace(
1324                        &mut self.pending_invalidation_diagnostics,
1325                        InvalidationTraceSample {
1326                            target: request.target,
1327                            kind: request.kind,
1328                            region: request.region,
1329                            source: format!("reactive:{}", sample.source_name),
1330                            reason: Some(format!("observable version {}", sample.version)),
1331                        },
1332                    );
1333                }
1334                self.pending_reactive_diagnostics.push(sample);
1335                if delivered {
1336                    targets.insert(widget_id);
1337                    invalidations.push(request);
1338                }
1339            }
1340
1341            for target in targets {
1342                let command = command::queued_command(
1343                    CommandTarget::Widget {
1344                        window_id: self.id,
1345                        widget_id: target,
1346                    },
1347                    CommandDelivery::Directed,
1348                    REACTIVE_CHANGED,
1349                    (),
1350                );
1351                let Some(dispatch) = self.dispatch_direct_command(target, &command) else {
1352                    continue;
1353                };
1354                let focus_request = dispatch.focus_request;
1355                let mut effects = EventEffects::default();
1356                effects.extend(dispatch);
1357                self.apply_event_effects(effects, &mut invalidations);
1358                if let Some(request) = focus_request {
1359                    let focus_effects = self.apply_focus_request(request);
1360                    self.apply_event_effects(focus_effects, &mut invalidations);
1361                }
1362            }
1363
1364            self.schedule.extend(&invalidations);
1365            self.pending_invalidations.extend(invalidations);
1366        }
1367    }
1368
1369    fn needs_render(&self) -> bool {
1370        self.last_frame.is_none() || self.schedule.needs_render() || self.reactive_hub.has_pending()
1371    }
1372
1373    fn handle_event(
1374        &mut self,
1375        event: Event,
1376        text_system: Arc<TextSystem>,
1377        font_registry: Arc<FontRegistry>,
1378        image_registry: Arc<ImageRegistry>,
1379    ) -> bool {
1380        if matches!(event, Event::Window(WindowEvent::RedrawRequested)) {
1381            diagnostics::begin_widget_timing_collection();
1382            sui_text::begin_text_timing_collection();
1383        }
1384        if matches!(event, Event::Wake(WakeEvent::AnimationFrame { .. })) {
1385            self.pending_animation_wake_count = self.pending_animation_wake_count.saturating_add(1);
1386        }
1387        if let Event::Pointer(pointer) = &event {
1388            self.last_pointer_events
1389                .insert(pointer.pointer_id, pointer.clone());
1390        }
1391
1392        self.preprocess_window_event(&event);
1393        self.ensure_graph_for_event(&event, text_system, font_registry, image_registry);
1394
1395        let mut invalidations = Vec::new();
1396        self.apply_pending_overlay_focus(&mut invalidations);
1397
1398        let captured_target = match &event {
1399            Event::Pointer(pointer) => self.pointer_capture.get(&pointer.pointer_id).copied(),
1400            _ => None,
1401        };
1402
1403        let pointer_hit_target = match &event {
1404            Event::Pointer(pointer) => self.pointer_hit_target(pointer.position),
1405            _ => None,
1406        };
1407        let mut hit_target = match &event {
1408            Event::Pointer(_) if captured_target.is_some() => None,
1409            Event::Pointer(_) => pointer_hit_target,
1410            _ => None,
1411        };
1412
1413        if matches!(event, Event::Window(WindowEvent::Focused(false))) {
1414            self.cancel_all_pointer_captures(&mut invalidations);
1415            self.pointer_capture.clear();
1416            self.last_pointer_events.clear();
1417            self.active_drag = None;
1418        }
1419        let mut skip_primary_route = false;
1420        if let Event::Pointer(pointer) = &event {
1421            let hover_route = self.update_pointer_hover_path(pointer, hit_target);
1422            self.apply_event_effects(hover_route.effects, &mut invalidations);
1423
1424            if let Some(request) = hover_route.focus_request {
1425                let focus_effects = self.apply_focus_request(request);
1426                self.apply_event_effects(focus_effects, &mut invalidations);
1427            }
1428
1429            skip_primary_route = hover_route.skip_primary_route;
1430        }
1431
1432        if skip_primary_route {
1433            self.finish_event(&event);
1434            self.record_event_invalidations(&invalidations, &event);
1435            self.schedule.extend(&invalidations);
1436            self.pending_invalidations.extend(invalidations);
1437            return false;
1438        }
1439
1440        if matches!(
1441            &event,
1442            Event::Keyboard(key)
1443                if key.state == KeyState::Pressed
1444                    && key.key == "BrowserBack"
1445                    && !key.repeat
1446                    && !key.is_composing
1447        ) && self.ime_composition_rect.is_some()
1448            && self.focus.focused_widget.is_some()
1449        {
1450            // Android exposes its system Back key as `BrowserBack`. When an editor has
1451            // enabled the IME, the first press dismisses editing instead of closing the
1452            // containing window. This clear deliberately bypasses modal focus trapping:
1453            // keeping logical focus would cause the next frame to enable the IME again.
1454            self.ime_composition_rect = None;
1455            let effects = self.apply_focus_request_unconstrained(FocusRequest::Clear);
1456            self.apply_event_effects(effects, &mut invalidations);
1457            self.finish_event(&event);
1458            self.record_event_invalidations(&invalidations, &event);
1459            self.schedule.extend(&invalidations);
1460            self.pending_invalidations.extend(invalidations);
1461            return true;
1462        }
1463
1464        if matches!(
1465            &event,
1466            Event::Keyboard(key)
1467                if key.state == KeyState::Pressed
1468                    && matches!(key.key.as_str(), "Escape" | "BrowserBack")
1469                    && !key.repeat
1470                    && !key.is_composing
1471        ) && self.dispatch_overlay_dismissal(
1472            OverlayDismissReason::Escape,
1473            None,
1474            &mut invalidations,
1475        ) {
1476            self.finish_event(&event);
1477            self.record_event_invalidations(&invalidations, &event);
1478            self.schedule.extend(&invalidations);
1479            self.pending_invalidations.extend(invalidations);
1480            return true;
1481        }
1482
1483        if let Event::Pointer(pointer) = &event
1484            && pointer.kind == PointerEventKind::Down
1485            && pointer.button == Some(PointerButton::Primary)
1486            && let Some(entry) = self
1487                .overlay_manager
1488                .topmost_dismissible(OverlayDismissReason::OutsidePointer)
1489                .cloned()
1490            && !hit_target.is_some_and(|target| self.target_is_in_overlay(entry.owner, target))
1491        {
1492            self.dispatch_overlay_dismissal(
1493                OverlayDismissReason::OutsidePointer,
1494                Some(pointer.position),
1495                &mut invalidations,
1496            );
1497        }
1498
1499        if let Some(modal) = self.overlay_manager.active_modal()
1500            && hit_target.is_some_and(|target| !self.target_is_in_overlay(modal, target))
1501        {
1502            hit_target = Some(modal);
1503        }
1504
1505        let target = self.resolve_event_target(&event, hit_target);
1506
1507        let route = self.route_event(target, &event);
1508        let handled = route.handled;
1509
1510        let focus_request = route
1511            .focus_request
1512            .or_else(|| self.default_focus_request(&event, hit_target, &route.path));
1513        self.apply_event_effects(route.effects, &mut invalidations);
1514
1515        if let Some(request) = focus_request {
1516            let focus_effects = self.apply_focus_request(request);
1517            self.apply_event_effects(focus_effects, &mut invalidations);
1518        }
1519
1520        if let Event::Pointer(pointer) = &event {
1521            let drag_effects = self.handle_drag_pointer_event(pointer, pointer_hit_target);
1522            self.apply_event_effects(drag_effects, &mut invalidations);
1523        }
1524
1525        self.finish_event(&event);
1526        self.record_event_invalidations(&invalidations, &event);
1527        self.schedule.extend(&invalidations);
1528        self.pending_invalidations.extend(invalidations);
1529        handled
1530    }
1531
1532    fn record_event_invalidations(&mut self, invalidations: &[InvalidationRequest], event: &Event) {
1533        let source = event_trace_source(event);
1534        extend_traces(
1535            &mut self.pending_invalidation_diagnostics,
1536            invalidations.iter().map(|request| InvalidationTraceSample {
1537                target: request.target,
1538                kind: request.kind,
1539                region: request.region,
1540                source: source.clone(),
1541                reason: None,
1542            }),
1543        );
1544    }
1545
1546    fn target_is_in_overlay(&self, owner: WidgetId, target: WidgetId) -> bool {
1547        target == owner || self.graph.is_ancestor_of(owner, target)
1548    }
1549
1550    fn dispatch_overlay_dismissal(
1551        &mut self,
1552        reason: OverlayDismissReason,
1553        pointer_position: Option<Point>,
1554        invalidations: &mut Vec<InvalidationRequest>,
1555    ) -> bool {
1556        let Some(entry) = self.overlay_manager.topmost_dismissible(reason).cloned() else {
1557            return false;
1558        };
1559        let mut request = OverlayDismissRequest::new(reason);
1560        request.pointer_position = pointer_position;
1561        let queued = command::queued_command(
1562            CommandTarget::Widget {
1563                window_id: self.id,
1564                widget_id: entry.owner,
1565            },
1566            CommandDelivery::Directed,
1567            OVERLAY_DISMISS_REQUEST,
1568            request,
1569        );
1570        let Some(dispatch) = self.dispatch_direct_command(entry.owner, &queued) else {
1571            return false;
1572        };
1573        let handled = dispatch.handled;
1574        let focus_request = dispatch.focus_request;
1575        let mut effects = EventEffects::default();
1576        effects.extend(dispatch);
1577        self.apply_event_effects(effects, invalidations);
1578        if let Some(request) = focus_request {
1579            let effects = self.apply_focus_request(request);
1580            self.apply_event_effects(effects, invalidations);
1581        }
1582        if handled {
1583            self.overlay_manager
1584                .trace_dismissal(entry.owner, entry.options.kind, reason);
1585        }
1586        handled
1587    }
1588
1589    fn handle_semantics_action(
1590        &mut self,
1591        target: WidgetId,
1592        action: SemanticsActionRequest,
1593        text_system: Arc<TextSystem>,
1594        font_registry: Arc<FontRegistry>,
1595        image_registry: Arc<ImageRegistry>,
1596    ) -> bool {
1597        let Some(node) = self
1598            .last_semantics
1599            .iter()
1600            .find(|node| node.id == target)
1601            .cloned()
1602        else {
1603            return false;
1604        };
1605
1606        if node.state.hidden
1607            || node.state.disabled
1608            || !node.actions.contains(&action.advertised_action())
1609        {
1610            return false;
1611        }
1612
1613        if matches!(
1614            (&action, node.state.expanded),
1615            (SemanticsActionRequest::Expand, Some(true))
1616                | (SemanticsActionRequest::Collapse, Some(false))
1617        ) {
1618            return true;
1619        }
1620
1621        let event = Event::Semantics(SemanticsEvent::new(target, action.clone()));
1622        self.ensure_graph_for_event(
1623            &event,
1624            Arc::clone(&text_system),
1625            Arc::clone(&font_registry),
1626            Arc::clone(&image_registry),
1627        );
1628
1629        let route_target = self.semantics_route_target(target);
1630        let route = self.route_event(route_target, &event);
1631        let handled = route.handled;
1632        let semantics_was_focused = self.focused_semantics == Some(target);
1633        let mut focus_request = route.focus_request;
1634        let widget_requested_focus = matches!(focus_request, Some(FocusRequest::Focus(_)));
1635        let mut focus_succeeded = false;
1636        let mut invalidations = Vec::new();
1637        self.apply_event_effects(route.effects, &mut invalidations);
1638
1639        match action {
1640            SemanticsActionRequest::Focus => {
1641                let runtime_focus_request = focus_request
1642                    .is_none()
1643                    .then(|| self.focus_request_for(route_target))
1644                    .flatten();
1645                focus_succeeded =
1646                    handled || widget_requested_focus || runtime_focus_request.is_some();
1647                focus_request = focus_request.or(runtime_focus_request);
1648            }
1649            SemanticsActionRequest::Blur if semantics_was_focused => {
1650                focus_request = Some(FocusRequest::Clear);
1651            }
1652            _ => {}
1653        }
1654
1655        if let Some(request) = focus_request {
1656            let focus_effects = self.apply_focus_request(request);
1657            self.apply_event_effects(focus_effects, &mut invalidations);
1658        }
1659
1660        match action {
1661            SemanticsActionRequest::Focus if focus_succeeded => {
1662                self.focused_semantics = Some(target);
1663                self.schedule.mark(InvalidationKind::Semantics);
1664            }
1665            SemanticsActionRequest::Blur if semantics_was_focused => {
1666                self.focused_semantics = None;
1667                self.schedule.mark(InvalidationKind::Semantics);
1668            }
1669            _ => {}
1670        }
1671
1672        self.schedule.extend(&invalidations);
1673        self.pending_invalidations.extend(invalidations);
1674
1675        let pointer_fallback = matches!(
1676            action,
1677            SemanticsActionRequest::Activate
1678                | SemanticsActionRequest::Expand
1679                | SemanticsActionRequest::Collapse
1680        );
1681        if pointer_fallback && !handled && !node.bounds.is_empty() {
1682            self.dispatch_semantics_pointer_activation(
1683                node.bounds,
1684                text_system,
1685                font_registry,
1686                image_registry,
1687            );
1688            return true;
1689        }
1690
1691        handled
1692            || matches!(action, SemanticsActionRequest::Focus) && focus_succeeded
1693            || matches!(action, SemanticsActionRequest::Blur) && semantics_was_focused
1694    }
1695
1696    fn semantics_route_target(&self, target: WidgetId) -> WidgetId {
1697        let mut current = Some(target);
1698        let mut visited = HashSet::new();
1699
1700        while let Some(candidate) = current {
1701            if !visited.insert(candidate) {
1702                break;
1703            }
1704            if self.graph.contains(candidate) {
1705                return candidate;
1706            }
1707            current = self
1708                .last_semantics
1709                .iter()
1710                .find(|node| node.id == candidate)
1711                .and_then(|node| node.parent);
1712        }
1713
1714        self.root.id()
1715    }
1716
1717    fn focus_request_for(&self, target: WidgetId) -> Option<FocusRequest> {
1718        self.graph.path_to(target).and_then(|path| {
1719            path.into_iter()
1720                .rev()
1721                .find(|widget_id| {
1722                    self.graph
1723                        .node(*widget_id)
1724                        .is_some_and(|node| node.accepts_focus)
1725                })
1726                .map(FocusRequest::Focus)
1727        })
1728    }
1729
1730    fn dispatch_semantics_pointer_activation(
1731        &mut self,
1732        bounds: Rect,
1733        text_system: Arc<TextSystem>,
1734        font_registry: Arc<FontRegistry>,
1735        image_registry: Arc<ImageRegistry>,
1736    ) {
1737        let position = Point::new(
1738            bounds.x() + bounds.width() * 0.5,
1739            bounds.y() + bounds.height() * 0.5,
1740        );
1741
1742        let mut down = PointerEvent::new(PointerEventKind::Down, position);
1743        down.button = Some(PointerButton::Primary);
1744        down.buttons.insert(PointerButton::Primary);
1745        self.handle_event(
1746            Event::Pointer(down),
1747            Arc::clone(&text_system),
1748            Arc::clone(&font_registry),
1749            Arc::clone(&image_registry),
1750        );
1751
1752        let mut up = PointerEvent::new(PointerEventKind::Up, position);
1753        up.button = Some(PointerButton::Primary);
1754        self.handle_event(
1755            Event::Pointer(up),
1756            text_system,
1757            font_registry,
1758            image_registry,
1759        );
1760    }
1761
1762    fn update_pointer_hover_path(
1763        &mut self,
1764        pointer: &PointerEvent,
1765        hit_target: Option<WidgetId>,
1766    ) -> HoverTransitionResult {
1767        let skip_primary_route = matches!(
1768            pointer.kind,
1769            PointerEventKind::Enter | PointerEventKind::Leave
1770        );
1771
1772        let next_path = match pointer.kind {
1773            PointerEventKind::Move | PointerEventKind::Enter
1774                if pointer.buttons.is_empty()
1775                    && !self.pointer_capture.contains_key(&pointer.pointer_id) =>
1776            {
1777                self.hover_transition_path(hit_target)
1778            }
1779            PointerEventKind::Leave | PointerEventKind::Cancel => Vec::new(),
1780            _ => {
1781                return HoverTransitionResult {
1782                    skip_primary_route,
1783                    ..HoverTransitionResult::default()
1784                };
1785            }
1786        };
1787
1788        let previous_path = self
1789            .pointer_hover_paths
1790            .remove(&pointer.pointer_id)
1791            .unwrap_or_default();
1792        if previous_path == next_path {
1793            if !next_path.is_empty() {
1794                self.pointer_hover_paths
1795                    .insert(pointer.pointer_id, next_path);
1796            }
1797            return HoverTransitionResult {
1798                skip_primary_route,
1799                ..HoverTransitionResult::default()
1800            };
1801        }
1802
1803        let shared_prefix_len = previous_path
1804            .iter()
1805            .zip(next_path.iter())
1806            .take_while(|(left, right)| left == right)
1807            .count();
1808
1809        let mut result = HoverTransitionResult {
1810            skip_primary_route,
1811            ..HoverTransitionResult::default()
1812        };
1813
1814        let mut leave_pointer = pointer.clone();
1815        leave_pointer.kind = PointerEventKind::Leave;
1816        let leave_event = Event::Pointer(leave_pointer);
1817        for widget_id in previous_path[shared_prefix_len..].iter().rev().copied() {
1818            let dispatch = self.dispatch_direct_event(widget_id, &leave_event);
1819            let dispatch_focus_request = dispatch.focus_request;
1820            result.effects.extend(dispatch);
1821            if dispatch_focus_request.is_some() {
1822                result.focus_request = dispatch_focus_request;
1823            }
1824        }
1825
1826        let mut enter_pointer = pointer.clone();
1827        enter_pointer.kind = PointerEventKind::Enter;
1828        let enter_event = Event::Pointer(enter_pointer);
1829        for widget_id in next_path[shared_prefix_len..].iter().copied() {
1830            let dispatch = self.dispatch_direct_event(widget_id, &enter_event);
1831            let dispatch_focus_request = dispatch.focus_request;
1832            result.effects.extend(dispatch);
1833            if dispatch_focus_request.is_some() {
1834                result.focus_request = dispatch_focus_request;
1835            }
1836        }
1837
1838        if !next_path.is_empty() {
1839            self.pointer_hover_paths
1840                .insert(pointer.pointer_id, next_path);
1841        }
1842
1843        result
1844    }
1845
1846    fn hover_transition_path(&self, hit_target: Option<WidgetId>) -> Vec<WidgetId> {
1847        hit_target
1848            .and_then(|target| self.graph.path_to(target))
1849            .map(|path| path.into_iter().skip(1).collect())
1850            .unwrap_or_default()
1851    }
1852
1853    fn dispatch_direct_event(&mut self, target: WidgetId, event: &Event) -> widget::EventDispatch {
1854        let path = self.graph.path_to(target);
1855        let dpi_info = self.current_dpi_info();
1856        self.root
1857            .dispatch_event_for_path(
1858                path.as_deref().unwrap_or(&[self.root.id()]),
1859                self.id,
1860                dpi_info,
1861                self.last_tick_time,
1862                EventPhase::Target,
1863                self.focus.focused_widget,
1864                &self.clipboard,
1865                &self.command_sender,
1866                event,
1867            )
1868            .or_else(|| {
1869                self.root.dispatch_event_for(
1870                    target,
1871                    self.id,
1872                    dpi_info,
1873                    self.last_tick_time,
1874                    EventPhase::Target,
1875                    self.focus.focused_widget,
1876                    &self.clipboard,
1877                    &self.command_sender,
1878                    event,
1879                )
1880            })
1881            .unwrap_or_else(empty_dispatch)
1882    }
1883
1884    fn dispatch_direct_command(
1885        &mut self,
1886        target: WidgetId,
1887        command: &QueuedCommand,
1888    ) -> Option<widget::EventDispatch> {
1889        let path = if target == self.root.id() {
1890            vec![target]
1891        } else {
1892            self.graph.path_to(target)?
1893        };
1894        let dpi_info = self.current_dpi_info();
1895        let command = Command::new(command);
1896        self.root
1897            .dispatch_command_for_path(
1898                &path,
1899                self.id,
1900                dpi_info,
1901                self.last_tick_time,
1902                self.focus.focused_widget,
1903                &self.clipboard,
1904                &self.command_sender,
1905                &command,
1906            )
1907            .or_else(|| {
1908                self.root.dispatch_command_for(
1909                    target,
1910                    self.id,
1911                    dpi_info,
1912                    self.last_tick_time,
1913                    self.focus.focused_widget,
1914                    &self.clipboard,
1915                    &self.command_sender,
1916                    &command,
1917                )
1918            })
1919    }
1920
1921    fn record_command_invalidations(
1922        &mut self,
1923        invalidations: &[InvalidationRequest],
1924        source: &str,
1925        reason: Option<&str>,
1926    ) {
1927        extend_traces(
1928            &mut self.pending_invalidation_diagnostics,
1929            invalidations.iter().map(|request| InvalidationTraceSample {
1930                target: request.target,
1931                kind: request.kind,
1932                region: request.region,
1933                source: format!("command:{source}"),
1934                reason: reason.map(str::to_string),
1935            }),
1936        );
1937    }
1938
1939    fn pointer_hit_target(&mut self, point: Point) -> Option<WidgetId> {
1940        let floating_hit = self.floating_layer_hit_test(point);
1941        let focused_floating_hit = if floating_hit.is_none() {
1942            self.focused_floating_layer_hit_test(point)
1943        } else {
1944            None
1945        };
1946        floating_hit
1947            .or(focused_floating_hit)
1948            .or_else(|| self.graph.hit_test(point))
1949    }
1950
1951    fn floating_layer_hit_test(&mut self, point: Point) -> Option<WidgetId> {
1952        let effect_hit = {
1953            let scene = self.last_frame.as_ref().map(|frame| &frame.scene)?;
1954            scene_hit_test_for_phase(
1955                scene,
1956                point,
1957                HitTestCompositionPhase::Effect,
1958                HitTestCompositionPhase::Normal,
1959            )
1960        };
1961        if let Some(widget_id) = effect_hit
1962            && self
1963                .current_widget_matches_hit_test_phase(widget_id, HitTestCompositionPhase::Effect)
1964        {
1965            return self
1966                .graph
1967                .hit_test_within(widget_id, point)
1968                .or(Some(widget_id));
1969        }
1970
1971        let overlay_hit = {
1972            let scene = self.last_frame.as_ref().map(|frame| &frame.scene)?;
1973            scene_hit_test_for_phase(
1974                scene,
1975                point,
1976                HitTestCompositionPhase::Overlay,
1977                HitTestCompositionPhase::Normal,
1978            )
1979        };
1980        overlay_hit.and_then(|widget_id| {
1981            self.current_widget_matches_hit_test_phase(widget_id, HitTestCompositionPhase::Overlay)
1982                .then(|| {
1983                    self.graph
1984                        .hit_test_within(widget_id, point)
1985                        .unwrap_or(widget_id)
1986                })
1987        })
1988    }
1989
1990    fn focused_floating_layer_hit_test(&mut self, point: Point) -> Option<WidgetId> {
1991        let focused = self.focus.focused_widget?;
1992        if !self.current_widget_matches_hit_test_phase(focused, HitTestCompositionPhase::Overlay)
1993            && !self.current_widget_matches_hit_test_phase(focused, HitTestCompositionPhase::Effect)
1994        {
1995            return None;
1996        }
1997
1998        let scene = self.last_frame.as_ref().map(|frame| &frame.scene)?;
1999        let descriptor = collect_scene_layers(scene).get(&focused)?.clone();
2000        (descriptor.hit_test && descriptor.paint_bounds.contains(point)).then_some(focused)
2001    }
2002
2003    fn current_widget_matches_hit_test_phase(
2004        &mut self,
2005        widget_id: WidgetId,
2006        target_phase: HitTestCompositionPhase,
2007    ) -> bool {
2008        if !self.graph.node(widget_id).is_some_and(|node| node.hit_test) {
2009            return false;
2010        }
2011        let Some(composition_mode) = self.current_widget_composition_mode(widget_id) else {
2012            return false;
2013        };
2014
2015        next_hit_test_phase(HitTestCompositionPhase::Normal, composition_mode) == target_phase
2016    }
2017
2018    fn current_widget_composition_mode(
2019        &mut self,
2020        widget_id: WidgetId,
2021    ) -> Option<LayerCompositionMode> {
2022        self.root.layer_composition_mode_for(widget_id)
2023    }
2024
2025    fn animation_frame_deadline(&self) -> Option<f64> {
2026        (!self.requested_animation_frames.is_empty()).then_some(
2027            self.last_animation_frame_time
2028                .map_or(self.last_tick_time, |last| {
2029                    last + ANIMATION_FRAME_INTERVAL_SECONDS
2030                }),
2031        )
2032    }
2033
2034    fn next_wakeup_time(&self) -> Option<f64> {
2035        let mut next = self
2036            .scheduled_timers
2037            .iter()
2038            .map(|timer| timer.deadline)
2039            .min_by(|left, right| left.total_cmp(right));
2040
2041        if !self.pending_async_wakeups.is_empty() {
2042            next = Some(next.map_or(self.last_tick_time, |deadline| {
2043                deadline.min(self.last_tick_time)
2044            }));
2045        }
2046
2047        if let Some(animation_deadline) = self.animation_frame_deadline() {
2048            next = Some(next.map_or(animation_deadline, |deadline| {
2049                deadline.min(animation_deadline)
2050            }));
2051        }
2052
2053        next
2054    }
2055
2056    fn active_animated_widget_count(&self) -> usize {
2057        self.requested_animation_frames
2058            .iter()
2059            .copied()
2060            .chain(self.delivering_animation_frames.iter().copied())
2061            .collect::<BTreeSet<_>>()
2062            .len()
2063    }
2064
2065    fn animation_frame_is_transform_only(
2066        &self,
2067        repainted: bool,
2068        layer_updates: &[SceneLayerUpdate],
2069    ) -> bool {
2070        !repainted
2071            && !layer_updates.is_empty()
2072            && layer_updates.iter().all(|update| {
2073                matches!(
2074                    update.kind,
2075                    SceneLayerUpdateKind::Transform
2076                        | SceneLayerUpdateKind::Effect
2077                        | SceneLayerUpdateKind::Visibility
2078                )
2079            })
2080    }
2081
2082    fn drain_ready_events(&mut self) -> Vec<Event> {
2083        let now = self.last_tick_time;
2084        let mut ready = Vec::new();
2085        let mut pending_timers = Vec::with_capacity(self.scheduled_timers.len());
2086
2087        for timer in self.scheduled_timers.drain(..) {
2088            if timer.deadline <= now {
2089                self.delivering_timers.insert(timer.token, timer.target);
2090                ready.push(Event::Wake(WakeEvent::Timer {
2091                    token: timer.token,
2092                    time: now,
2093                    deadline: timer.deadline,
2094                }));
2095            } else {
2096                pending_timers.push(timer);
2097            }
2098        }
2099        self.scheduled_timers = pending_timers;
2100
2101        while let Some(token) = self.pending_async_wakeups.pop_front() {
2102            if self.async_wake_targets.contains_key(&token) {
2103                ready.push(Event::Wake(WakeEvent::Async { token, time: now }));
2104            }
2105        }
2106
2107        if self
2108            .animation_frame_deadline()
2109            .is_some_and(|deadline| deadline <= now)
2110        {
2111            let delta = self
2112                .last_animation_frame_time
2113                .map(|last| (now - last).max(0.0))
2114                .unwrap_or(0.0);
2115            let frame_index = self.next_animation_frame_index;
2116            self.next_animation_frame_index = self.next_animation_frame_index.saturating_add(1);
2117
2118            let requested = std::mem::take(&mut self.requested_animation_frames);
2119            self.delivering_animation_frames
2120                .extend(requested.iter().copied());
2121            ready.extend(requested.iter().map(|_| {
2122                Event::Wake(WakeEvent::AnimationFrame {
2123                    time: now,
2124                    delta,
2125                    frame_index,
2126                })
2127            }));
2128            self.last_animation_frame_time = Some(now);
2129        } else if self.delivering_animation_frames.is_empty()
2130            && self.requested_animation_frames.is_empty()
2131        {
2132            self.last_animation_frame_time = None;
2133        }
2134
2135        ready
2136    }
2137
2138    fn wake_async(&mut self, token: AsyncWakeToken) -> bool {
2139        if !self.async_wake_targets.contains_key(&token) {
2140            return false;
2141        }
2142
2143        self.pending_async_wakeups.push_back(token);
2144        true
2145    }
2146
2147    /// A viewport (window) resize or DPI change can reflow every widget, so it must
2148    /// force a full re-measure rather than a scoped one. Marking the schedule alone is
2149    /// not enough: `build_measure_scope` only re-measures the whole tree when it sees a
2150    /// `Window`/`Surface` invalidation (or none at all), so record one explicitly —
2151    /// otherwise stale per-widget invalidations would scope the pass and width-responsive
2152    /// subtrees would keep their old bounds, failing to reflow on resize.
2153    fn invalidate_layout_for_viewport_change(&mut self) {
2154        self.schedule.mark(InvalidationKind::Measure);
2155        self.pending_invalidations.push(InvalidationRequest::new(
2156            InvalidationTarget::Window(self.id),
2157            InvalidationKind::Measure,
2158        ));
2159    }
2160
2161    fn preprocess_window_event(&mut self, event: &Event) {
2162        let Event::Window(window_event) = event else {
2163            return;
2164        };
2165
2166        match window_event {
2167            WindowEvent::Resized(size) => {
2168                self.viewport_hint = Some(*size);
2169                self.invalidate_layout_for_viewport_change();
2170            }
2171            WindowEvent::ScaleFactorChanged {
2172                scale_factor,
2173                raw_dpi,
2174                suggested_size,
2175            } => {
2176                self.scale_factor = *scale_factor as f32;
2177                self.raw_dpi = *raw_dpi;
2178                if let Some(size) = suggested_size {
2179                    self.viewport_hint = Some(*size);
2180                }
2181                self.invalidate_layout_for_viewport_change();
2182            }
2183            WindowEvent::SafeAreaChanged(safe_area) => {
2184                let safe_area = safe_area.normalized();
2185                if self.safe_area != safe_area {
2186                    self.safe_area = safe_area;
2187                    self.invalidate_layout_for_viewport_change();
2188                }
2189            }
2190            WindowEvent::Focused(focused) => {
2191                self.focus.window_focused = *focused;
2192            }
2193            WindowEvent::RedrawRequested => {
2194                self.schedule.mark(InvalidationKind::Paint);
2195            }
2196            WindowEvent::CloseRequested
2197            | WindowEvent::Occluded(_)
2198            | WindowEvent::ExternalFileHovered(_)
2199            | WindowEvent::ExternalFileHoverCancelled
2200            | WindowEvent::ExternalFileDropped(_) => {}
2201        }
2202    }
2203
2204    fn ensure_graph_for_event(
2205        &mut self,
2206        event: &Event,
2207        text_system: Arc<TextSystem>,
2208        font_registry: Arc<FontRegistry>,
2209        image_registry: Arc<ImageRegistry>,
2210    ) {
2211        if self.schedule.measure || self.schedule.arrange || self.viewport.is_none() {
2212            let scope_source = self.pending_invalidations.clone();
2213            let invalidations = self.run_measure_arrange_pass(
2214                &scope_source,
2215                text_system,
2216                font_registry,
2217                image_registry,
2218            );
2219            self.schedule.extend(&invalidations);
2220            self.pending_invalidations.extend(invalidations);
2221            return;
2222        }
2223
2224        if self.schedule.hit_test || self.graph.is_empty() {
2225            self.refresh_graph();
2226        }
2227
2228        if matches!(event, Event::Keyboard(_) | Event::Ime(_))
2229            && self.focus.focused_widget.is_some()
2230            && !self
2231                .graph
2232                .contains(self.focus.focused_widget.unwrap_or_default())
2233        {
2234            self.focus.focused_widget = None;
2235            self.focused_semantics = None;
2236        }
2237    }
2238
2239    fn resolve_event_target(&self, event: &Event, hit_target: Option<WidgetId>) -> WidgetId {
2240        match event {
2241            Event::Pointer(pointer) => self
2242                .pointer_capture
2243                .get(&pointer.pointer_id)
2244                .copied()
2245                .or(hit_target)
2246                .unwrap_or(self.root.id()),
2247            Event::Keyboard(_) | Event::Ime(_) => {
2248                self.focus.focused_widget.unwrap_or(self.root.id())
2249            }
2250            Event::Semantics(semantics) => self.semantics_route_target(semantics.target),
2251            Event::Wake(wake_event) => self.wake_target(*wake_event).unwrap_or(self.root.id()),
2252            _ => self.root.id(),
2253        }
2254    }
2255
2256    fn wake_target(&self, wake_event: WakeEvent) -> Option<WidgetId> {
2257        match wake_event {
2258            WakeEvent::Timer { token, .. } => self.delivering_timers.get(&token).copied(),
2259            WakeEvent::Async { token, .. } => self.async_wake_targets.get(&token).copied(),
2260            WakeEvent::AnimationFrame { .. } => self.delivering_animation_frames.front().copied(),
2261        }
2262    }
2263
2264    fn apply_event_effects(
2265        &mut self,
2266        effects: EventEffects,
2267        invalidations: &mut Vec<InvalidationRequest>,
2268    ) {
2269        invalidations.extend(effects.invalidations);
2270        self.apply_wake_requests(effects.wake_requests);
2271        self.apply_pointer_capture_requests(effects.pointer_capture_requests, invalidations);
2272        self.apply_drag_requests(effects.drag_requests, invalidations);
2273        self.apply_posted_events(effects.posted_events, invalidations);
2274        self.apply_posted_commands(effects.posted_commands, invalidations);
2275    }
2276
2277    /// Deliver widget-posted events (see `EventCtx::post_event`) directly to
2278    /// their targets. Posted events may post follow-ups; rounds are capped so
2279    /// two widgets posting at each other cannot wedge the event loop.
2280    fn apply_posted_events(
2281        &mut self,
2282        mut posted: Vec<widget::PostedEventRequest>,
2283        invalidations: &mut Vec<InvalidationRequest>,
2284    ) {
2285        const MAX_POSTED_EVENT_ROUNDS: usize = 8;
2286
2287        let mut rounds = 0;
2288        while !posted.is_empty() && rounds < MAX_POSTED_EVENT_ROUNDS {
2289            rounds += 1;
2290            for request in std::mem::take(&mut posted) {
2291                let dispatch = self.dispatch_direct_event(request.target, &request.event);
2292                invalidations.extend(dispatch.invalidations);
2293                self.apply_wake_requests(dispatch.wake_requests);
2294                self.apply_pointer_capture_requests(
2295                    dispatch.pointer_capture_requests,
2296                    invalidations,
2297                );
2298                self.apply_drag_requests(dispatch.drag_requests, invalidations);
2299                posted.extend(dispatch.posted_events);
2300                self.apply_posted_commands(dispatch.posted_commands, invalidations);
2301                if let Some(request) = dispatch.focus_request {
2302                    let focus_effects = self.apply_focus_request(request);
2303                    invalidations.extend(focus_effects.invalidations);
2304                    self.apply_wake_requests(focus_effects.wake_requests);
2305                    self.apply_pointer_capture_requests(
2306                        focus_effects.pointer_capture_requests,
2307                        invalidations,
2308                    );
2309                    self.apply_drag_requests(focus_effects.drag_requests, invalidations);
2310                    posted.extend(focus_effects.posted_events);
2311                    self.apply_posted_commands(focus_effects.posted_commands, invalidations);
2312                }
2313            }
2314        }
2315    }
2316
2317    fn apply_posted_commands(
2318        &mut self,
2319        mut posted: Vec<widget::PostedCommandRequest>,
2320        invalidations: &mut Vec<InvalidationRequest>,
2321    ) {
2322        const MAX_POSTED_COMMAND_ROUNDS: usize = 8;
2323        let mut rounds = 0;
2324        while !posted.is_empty() && rounds < MAX_POSTED_COMMAND_ROUNDS {
2325            rounds += 1;
2326            for request in std::mem::take(&mut posted) {
2327                let CommandTarget::Widget { widget_id, .. } = request.command.target else {
2328                    continue;
2329                };
2330                let Some(dispatch) = self.dispatch_direct_command(widget_id, &request.command)
2331                else {
2332                    push_trace(
2333                        &mut self.pending_command_diagnostics,
2334                        command_sample(&request.command, Vec::new(), false, false),
2335                    );
2336                    continue;
2337                };
2338                self.record_command_invalidations(
2339                    &dispatch.invalidations,
2340                    request.command.key.name,
2341                    Some("posted by widget"),
2342                );
2343                invalidations.extend(dispatch.invalidations);
2344                self.apply_wake_requests(dispatch.wake_requests);
2345                self.apply_pointer_capture_requests(
2346                    dispatch.pointer_capture_requests,
2347                    invalidations,
2348                );
2349                self.apply_drag_requests(dispatch.drag_requests, invalidations);
2350                self.apply_posted_events(dispatch.posted_events, invalidations);
2351                posted.extend(dispatch.posted_commands);
2352                push_trace(
2353                    &mut self.pending_command_diagnostics,
2354                    command_sample(
2355                        &request.command,
2356                        vec!["widget target".to_string()],
2357                        dispatch.handled,
2358                        true,
2359                    ),
2360                );
2361                if let Some(focus_request) = dispatch.focus_request {
2362                    let effects = self.apply_focus_request(focus_request);
2363                    self.apply_event_effects(effects, invalidations);
2364                }
2365            }
2366        }
2367    }
2368
2369    fn apply_drag_requests(
2370        &mut self,
2371        requests: Vec<DragRequest>,
2372        invalidations: &mut Vec<InvalidationRequest>,
2373    ) {
2374        for request in requests {
2375            match request {
2376                DragRequest::Begin(request) => {
2377                    self.active_drag = Some(ActiveDrag::from_request(request));
2378                    invalidations.push(InvalidationRequest::new(
2379                        InvalidationTarget::Window(self.id),
2380                        InvalidationKind::Paint,
2381                    ));
2382                }
2383            }
2384        }
2385    }
2386
2387    fn handle_drag_pointer_event(
2388        &mut self,
2389        pointer: &PointerEvent,
2390        hit_target: Option<WidgetId>,
2391    ) -> EventEffects {
2392        if self
2393            .active_drag
2394            .as_ref()
2395            .is_none_or(|drag| drag.pointer_id != pointer.pointer_id)
2396        {
2397            return EventEffects::default();
2398        }
2399
2400        match pointer.kind {
2401            PointerEventKind::Move => self.update_active_drag(pointer.position, hit_target),
2402            PointerEventKind::Up => {
2403                let mut effects = self.update_active_drag(pointer.position, hit_target);
2404                effects.merge(self.finish_active_drag(pointer.position, false));
2405                effects
2406            }
2407            PointerEventKind::Cancel | PointerEventKind::Leave => {
2408                self.finish_active_drag(pointer.position, true)
2409            }
2410            _ => EventEffects::default(),
2411        }
2412    }
2413
2414    fn update_active_drag(
2415        &mut self,
2416        position: Point,
2417        hit_target: Option<WidgetId>,
2418    ) -> EventEffects {
2419        let Some((previous_path, active_snapshot)) = self.active_drag.as_mut().map(|active| {
2420            active.position = position;
2421            (active.hover_path.clone(), active.clone())
2422        }) else {
2423            return EventEffects::default();
2424        };
2425
2426        let next_path = hit_target
2427            .and_then(|target| self.graph.path_to(target))
2428            .unwrap_or_default();
2429
2430        let mut effects = EventEffects::default();
2431        effects.invalidations.push(InvalidationRequest::new(
2432            InvalidationTarget::Window(self.id),
2433            InvalidationKind::Paint,
2434        ));
2435
2436        let shared_prefix_len = previous_path
2437            .iter()
2438            .zip(next_path.iter())
2439            .take_while(|(left, right)| left == right)
2440            .count();
2441
2442        for widget_id in previous_path[shared_prefix_len..].iter().rev().copied() {
2443            let event = active_snapshot.event(
2444                DragEventKind::Leave,
2445                position,
2446                Some(widget_id),
2447                DropEffect::None,
2448                None,
2449            );
2450            effects.extend(self.dispatch_direct_event(widget_id, &event));
2451        }
2452
2453        for widget_id in next_path[shared_prefix_len..].iter().copied() {
2454            let event = active_snapshot.event(
2455                DragEventKind::Enter,
2456                position,
2457                Some(widget_id),
2458                DropEffect::None,
2459                None,
2460            );
2461            effects.extend(self.dispatch_direct_event(widget_id, &event));
2462        }
2463
2464        let mut accepted = None;
2465        if let Some(target) = hit_target {
2466            let event = active_snapshot.event(
2467                DragEventKind::Over,
2468                position,
2469                Some(target),
2470                DropEffect::None,
2471                None,
2472            );
2473            let route = self.route_event(target, &event);
2474            accepted = nearest_drop_acceptance(&route.effects.drop_acceptances, &route.path);
2475            if let Some(request) = route.focus_request {
2476                effects.merge(self.apply_focus_request(request));
2477            }
2478            effects.merge(route.effects);
2479        }
2480
2481        if let Some(active) = self.active_drag.as_mut() {
2482            active.hover_path = next_path;
2483            if let Some(accepted) = accepted {
2484                active.accepted_target = Some(accepted.target);
2485                active.accepted_effect = accepted.effect;
2486            } else {
2487                active.accepted_target = None;
2488                active.accepted_effect = DropEffect::None;
2489            }
2490        }
2491
2492        effects
2493    }
2494
2495    fn finish_active_drag(&mut self, position: Point, cancelled: bool) -> EventEffects {
2496        let Some(active) = self.active_drag.take() else {
2497            return EventEffects::default();
2498        };
2499
2500        let mut effects = EventEffects::default();
2501        let outcome = if !cancelled {
2502            active
2503                .accepted_target
2504                .filter(|_| active.accepted_effect.is_some())
2505                .map(|target| DragOutcome::Dropped {
2506                    target,
2507                    effect: active.accepted_effect,
2508                })
2509                .unwrap_or(DragOutcome::Cancelled)
2510        } else {
2511            DragOutcome::Cancelled
2512        };
2513
2514        if let DragOutcome::Dropped { target, effect } = outcome {
2515            let event = active.event(
2516                DragEventKind::Drop,
2517                position,
2518                Some(target),
2519                effect,
2520                Some(outcome),
2521            );
2522            effects.extend(self.dispatch_direct_event(target, &event));
2523        }
2524
2525        for widget_id in active.hover_path.iter().rev().copied() {
2526            let event = active.event(
2527                DragEventKind::Leave,
2528                position,
2529                Some(widget_id),
2530                DropEffect::None,
2531                None,
2532            );
2533            effects.extend(self.dispatch_direct_event(widget_id, &event));
2534        }
2535
2536        let end_event = active.event(
2537            DragEventKind::End,
2538            position,
2539            active.accepted_target,
2540            active.accepted_effect,
2541            Some(outcome),
2542        );
2543        effects.extend(self.dispatch_direct_event(active.source, &end_event));
2544        effects.invalidations.push(InvalidationRequest::new(
2545            InvalidationTarget::Window(self.id),
2546            InvalidationKind::Paint,
2547        ));
2548        effects
2549    }
2550
2551    fn apply_wake_requests(&mut self, requests: Vec<WakeRequest>) {
2552        for request in requests {
2553            match request {
2554                WakeRequest::ScheduleTimer {
2555                    token,
2556                    deadline,
2557                    target,
2558                } => {
2559                    self.scheduled_timers.retain(|timer| timer.token != token);
2560                    self.scheduled_timers.push(ScheduledTimer {
2561                        token,
2562                        deadline,
2563                        target,
2564                    });
2565                }
2566                WakeRequest::CancelTimer { token } => {
2567                    self.scheduled_timers.retain(|timer| timer.token != token);
2568                    self.delivering_timers.remove(&token);
2569                }
2570                WakeRequest::RegisterAsync { token, target } => {
2571                    self.async_wake_targets.insert(token, target);
2572                }
2573                WakeRequest::UnregisterAsync { token } => {
2574                    self.async_wake_targets.remove(&token);
2575                    self.pending_async_wakeups.retain(|queued| *queued != token);
2576                }
2577                WakeRequest::RequestAnimationFrame { target } => {
2578                    self.requested_animation_frames.insert(target);
2579                }
2580            }
2581        }
2582    }
2583
2584    fn apply_pointer_capture_requests(
2585        &mut self,
2586        requests: Vec<PointerCaptureRequest>,
2587        invalidations: &mut Vec<InvalidationRequest>,
2588    ) {
2589        for request in requests {
2590            match request {
2591                PointerCaptureRequest::Capture { pointer_id, target } => {
2592                    self.reconcile_pointer_capture(pointer_id, Some(target), invalidations);
2593                }
2594                PointerCaptureRequest::Release { pointer_id } => {
2595                    self.pointer_capture.remove(&pointer_id);
2596                }
2597            }
2598        }
2599    }
2600
2601    fn cancel_all_pointer_captures(&mut self, invalidations: &mut Vec<InvalidationRequest>) {
2602        let pointer_ids = self.pointer_capture.keys().copied().collect::<Vec<_>>();
2603        for pointer_id in pointer_ids {
2604            self.reconcile_pointer_capture(pointer_id, None, invalidations);
2605        }
2606    }
2607
2608    fn reconcile_pointer_capture(
2609        &mut self,
2610        pointer_id: u64,
2611        requested_target: Option<WidgetId>,
2612        invalidations: &mut Vec<InvalidationRequest>,
2613    ) {
2614        let mut cancelled_owners = HashSet::new();
2615
2616        loop {
2617            let current = self.pointer_capture.get(&pointer_id).copied();
2618            match (current, requested_target) {
2619                (None, Some(target)) => {
2620                    self.pointer_capture.insert(pointer_id, target);
2621                    return;
2622                }
2623                (None, None) => return,
2624                (Some(owner), Some(target)) if owner == target => return,
2625                (Some(owner), _) => {
2626                    self.pointer_capture.remove(&pointer_id);
2627                    if !cancelled_owners.insert(owner) {
2628                        // A cancellation handler may try to recapture synchronously. The original
2629                        // request remains authoritative, so suppress repeated ownership without
2630                        // dispatching an unbounded series of duplicate cancellation events.
2631                        continue;
2632                    }
2633
2634                    let cancel = self.pointer_cancel_event(pointer_id);
2635                    let dispatch = self.dispatch_direct_event(owner, &Event::Pointer(cancel));
2636                    self.apply_pointer_cancel_dispatch(dispatch, invalidations);
2637                }
2638            }
2639        }
2640    }
2641
2642    fn pointer_cancel_event(&self, pointer_id: u64) -> PointerEvent {
2643        let mut pointer = self
2644            .last_pointer_events
2645            .get(&pointer_id)
2646            .cloned()
2647            .unwrap_or_else(|| PointerEvent::new(PointerEventKind::Cancel, Point::ZERO));
2648        pointer.pointer_id = pointer_id;
2649        pointer.kind = PointerEventKind::Cancel;
2650        pointer.delta = Vector::ZERO;
2651        pointer.scroll_delta = None;
2652        pointer.button = None;
2653        pointer.buttons = PointerButtons::NONE;
2654        pointer
2655    }
2656
2657    fn apply_pointer_cancel_dispatch(
2658        &mut self,
2659        dispatch: widget::EventDispatch,
2660        invalidations: &mut Vec<InvalidationRequest>,
2661    ) {
2662        let focus_request = dispatch.focus_request;
2663        let mut effects = EventEffects::default();
2664        effects.extend(dispatch);
2665        self.apply_event_effects(effects, invalidations);
2666
2667        if let Some(request) = focus_request {
2668            let focus_effects = self.apply_focus_request(request);
2669            self.apply_event_effects(focus_effects, invalidations);
2670        }
2671    }
2672
2673    fn finish_event(&mut self, event: &Event) {
2674        match event {
2675            Event::Pointer(pointer)
2676                if matches!(
2677                    pointer.kind,
2678                    PointerEventKind::Up | PointerEventKind::Cancel
2679                ) =>
2680            {
2681                self.pointer_capture.remove(&pointer.pointer_id);
2682                self.last_pointer_events.remove(&pointer.pointer_id);
2683            }
2684            Event::Wake(WakeEvent::Timer { token, .. }) => {
2685                self.delivering_timers.remove(token);
2686            }
2687            Event::Wake(WakeEvent::AnimationFrame { .. }) => {
2688                self.delivering_animation_frames.pop_front();
2689                if self.delivering_animation_frames.is_empty()
2690                    && self.requested_animation_frames.is_empty()
2691                {
2692                    self.last_animation_frame_time = None;
2693                }
2694            }
2695            _ => {}
2696        }
2697    }
2698
2699    fn route_event(&mut self, target: WidgetId, event: &Event) -> EventRouteResult {
2700        let path = self
2701            .graph
2702            .path_to(target)
2703            .unwrap_or_else(|| vec![self.root.id()]);
2704        let dpi_info = self.current_dpi_info();
2705        let mut effects = EventEffects::default();
2706        let mut handled = false;
2707        let mut focus_request = None;
2708        let mut route_steps = self.inspector_tracing_enabled.then(Vec::new);
2709        let target_only = matches!(event, Event::Wake(_));
2710        let ignore_handled = matches!(event, Event::Drag(_));
2711
2712        if !target_only && path.len() > 1 {
2713            for path_len in 1..path.len() {
2714                let dispatch = self
2715                    .root
2716                    .dispatch_event_for_path(
2717                        &path[..path_len],
2718                        self.id,
2719                        dpi_info,
2720                        self.last_tick_time,
2721                        EventPhase::Capture,
2722                        self.focus.focused_widget,
2723                        &self.clipboard,
2724                        &self.command_sender,
2725                        event,
2726                    )
2727                    .unwrap_or_else(empty_dispatch);
2728                let dispatch_handled = dispatch.handled;
2729                let dispatch_focus_request = dispatch.focus_request;
2730                if let Some(route_steps) = &mut route_steps {
2731                    route_steps.push(EventRouteStep {
2732                        widget_id: path[path_len - 1],
2733                        phase: EventRoutePhase::Capture,
2734                        handled: dispatch_handled,
2735                    });
2736                }
2737                effects.extend(dispatch);
2738                if dispatch_focus_request.is_some() {
2739                    focus_request = dispatch_focus_request;
2740                }
2741                if dispatch_handled && !ignore_handled {
2742                    handled = true;
2743                    break;
2744                }
2745            }
2746        }
2747
2748        if !handled || ignore_handled {
2749            let dispatch = self
2750                .root
2751                .dispatch_event_for_path(
2752                    &path,
2753                    self.id,
2754                    dpi_info,
2755                    self.last_tick_time,
2756                    EventPhase::Target,
2757                    self.focus.focused_widget,
2758                    &self.clipboard,
2759                    &self.command_sender,
2760                    event,
2761                )
2762                .or_else(|| {
2763                    self.root.dispatch_event_for(
2764                        target,
2765                        self.id,
2766                        dpi_info,
2767                        self.last_tick_time,
2768                        EventPhase::Target,
2769                        self.focus.focused_widget,
2770                        &self.clipboard,
2771                        &self.command_sender,
2772                        event,
2773                    )
2774                })
2775                .unwrap_or_else(empty_dispatch);
2776            let dispatch_handled = dispatch.handled;
2777            let dispatch_focus_request = dispatch.focus_request;
2778            if let Some(route_steps) = &mut route_steps {
2779                route_steps.push(EventRouteStep {
2780                    widget_id: target,
2781                    phase: EventRoutePhase::Target,
2782                    handled: dispatch_handled,
2783                });
2784            }
2785            effects.extend(dispatch);
2786            if dispatch_focus_request.is_some() {
2787                focus_request = dispatch_focus_request;
2788            }
2789            handled = dispatch_handled && !ignore_handled;
2790        }
2791
2792        if !target_only && (!handled || ignore_handled) && path.len() > 1 {
2793            for path_len in (1..path.len()).rev() {
2794                let dispatch = self
2795                    .root
2796                    .dispatch_event_for_path(
2797                        &path[..path_len],
2798                        self.id,
2799                        dpi_info,
2800                        self.last_tick_time,
2801                        EventPhase::Bubble,
2802                        self.focus.focused_widget,
2803                        &self.clipboard,
2804                        &self.command_sender,
2805                        event,
2806                    )
2807                    .unwrap_or_else(empty_dispatch);
2808                let dispatch_handled = dispatch.handled;
2809                let dispatch_focus_request = dispatch.focus_request;
2810                if let Some(route_steps) = &mut route_steps {
2811                    route_steps.push(EventRouteStep {
2812                        widget_id: path[path_len - 1],
2813                        phase: EventRoutePhase::Bubble,
2814                        handled: dispatch_handled,
2815                    });
2816                }
2817                effects.extend(dispatch);
2818                if dispatch_focus_request.is_some() {
2819                    focus_request = dispatch_focus_request;
2820                }
2821                if dispatch_handled && !ignore_handled {
2822                    handled = true;
2823                    break;
2824                }
2825            }
2826        }
2827
2828        if let Some(route_steps) = route_steps {
2829            let trace_handled = route_steps.iter().any(|step| step.handled);
2830            let sample = EventRouteTraceSample {
2831                sequence: self.next_event_route_sequence,
2832                event_kind: inspector_event_kind(event),
2833                target,
2834                path: path.clone(),
2835                steps: route_steps,
2836                handled: trace_handled,
2837            };
2838            self.next_event_route_sequence = self.next_event_route_sequence.wrapping_add(1);
2839            push_inspector_history(&mut self.event_route_history, sample);
2840        }
2841
2842        EventRouteResult {
2843            path,
2844            effects,
2845            focus_request,
2846            handled,
2847        }
2848    }
2849
2850    fn default_focus_request(
2851        &self,
2852        event: &Event,
2853        hit_target: Option<WidgetId>,
2854        path: &[WidgetId],
2855    ) -> Option<FocusRequest> {
2856        match event {
2857            Event::Keyboard(keyboard)
2858                if keyboard.state == KeyState::Pressed
2859                    && keyboard.key == "Tab"
2860                    && !keyboard.repeat
2861                    && !keyboard.is_composing
2862                    && !keyboard.modifiers.control
2863                    && !keyboard.modifiers.alt
2864                    && !keyboard.modifiers.meta =>
2865            {
2866                self.overlay_manager
2867                    .focus_trap()
2868                    .and_then(|scope| {
2869                        self.graph.next_focusable_within(
2870                            scope,
2871                            self.focus.focused_widget,
2872                            keyboard.modifiers.shift,
2873                        )
2874                    })
2875                    .or_else(|| {
2876                        self.graph
2877                            .next_focusable(self.focus.focused_widget, keyboard.modifiers.shift)
2878                    })
2879                    .map(FocusRequest::Focus)
2880                    .or(Some(FocusRequest::Clear))
2881            }
2882            Event::Pointer(pointer) if pointer.kind == PointerEventKind::Down => {
2883                let Some(hit_target) = hit_target else {
2884                    return Some(FocusRequest::Clear);
2885                };
2886
2887                path.iter()
2888                    .rev()
2889                    .copied()
2890                    .find(|widget_id| {
2891                        self.graph
2892                            .node(*widget_id)
2893                            .is_some_and(|node| node.accepts_focus)
2894                    })
2895                    .map(FocusRequest::Focus)
2896                    .or(Some(FocusRequest::Clear))
2897                    .filter(|request| {
2898                        matches!(request, FocusRequest::Focus(id) if *id == hit_target)
2899                            || matches!(request, FocusRequest::Clear)
2900                    })
2901            }
2902            Event::Window(WindowEvent::Focused(false)) => Some(FocusRequest::Clear),
2903            _ => None,
2904        }
2905    }
2906
2907    fn apply_focus_request(&mut self, request: FocusRequest) -> EventEffects {
2908        let request = self.constrain_focus_request(request);
2909        self.apply_focus_request_unconstrained(request)
2910    }
2911
2912    fn apply_focus_request_unconstrained(&mut self, request: FocusRequest) -> EventEffects {
2913        let next_focus = match request {
2914            FocusRequest::Focus(widget_id) => Some(widget_id),
2915            FocusRequest::Clear => None,
2916        };
2917
2918        if self.focus.focused_widget == next_focus {
2919            if self.focused_semantics != next_focus {
2920                self.focused_semantics = next_focus;
2921                self.schedule.mark(InvalidationKind::Semantics);
2922            }
2923            return EventEffects::default();
2924        }
2925
2926        let previous_focus = self.focus.focused_widget;
2927        self.focus.focused_widget = next_focus;
2928        self.focused_semantics = next_focus;
2929        let dpi_info = self.current_dpi_info();
2930
2931        let mut effects = EventEffects::default();
2932
2933        if let Some(widget_id) = previous_focus {
2934            effects
2935                .invalidations
2936                .extend(self.focus_transition_invalidations(widget_id));
2937            let extra = self
2938                .graph
2939                .path_to(widget_id)
2940                .and_then(|path| {
2941                    self.root.notify_focus_change_for_path(
2942                        &path,
2943                        self.id,
2944                        dpi_info,
2945                        self.last_tick_time,
2946                        self.focus.focused_widget,
2947                        &self.clipboard,
2948                        &self.command_sender,
2949                        false,
2950                    )
2951                })
2952                .or_else(|| {
2953                    self.root.notify_focus_change_for(
2954                        widget_id,
2955                        self.id,
2956                        dpi_info,
2957                        self.last_tick_time,
2958                        self.focus.focused_widget,
2959                        &self.clipboard,
2960                        &self.command_sender,
2961                        false,
2962                    )
2963                });
2964            if let Some(extra) = extra {
2965                effects.extend(extra);
2966            }
2967        }
2968
2969        if let Some(widget_id) = next_focus {
2970            effects
2971                .invalidations
2972                .extend(self.focus_transition_invalidations(widget_id));
2973            let extra = self
2974                .graph
2975                .path_to(widget_id)
2976                .and_then(|path| {
2977                    self.root.notify_focus_change_for_path(
2978                        &path,
2979                        self.id,
2980                        dpi_info,
2981                        self.last_tick_time,
2982                        self.focus.focused_widget,
2983                        &self.clipboard,
2984                        &self.command_sender,
2985                        true,
2986                    )
2987                })
2988                .or_else(|| {
2989                    self.root.notify_focus_change_for(
2990                        widget_id,
2991                        self.id,
2992                        dpi_info,
2993                        self.last_tick_time,
2994                        self.focus.focused_widget,
2995                        &self.clipboard,
2996                        &self.command_sender,
2997                        true,
2998                    )
2999                });
3000            if let Some(extra) = extra {
3001                effects.extend(extra);
3002            }
3003        }
3004
3005        self.schedule.mark(InvalidationKind::Paint);
3006        self.schedule.mark(InvalidationKind::Semantics);
3007        self.schedule.mark(InvalidationKind::HitTest);
3008        self.graph.set_focused_widget(self.focus.focused_widget);
3009
3010        effects
3011    }
3012
3013    fn constrain_focus_request(&self, request: FocusRequest) -> FocusRequest {
3014        let Some(scope) = self.overlay_manager.focus_trap() else {
3015            return request;
3016        };
3017        match request {
3018            FocusRequest::Focus(widget_id)
3019                if widget_id == scope || self.graph.is_ancestor_of(scope, widget_id) =>
3020            {
3021                return request;
3022            }
3023            FocusRequest::Focus(_) | FocusRequest::Clear => {}
3024        }
3025
3026        self.focus
3027            .focused_widget
3028            .filter(|focused| *focused == scope || self.graph.is_ancestor_of(scope, *focused))
3029            .or_else(|| self.graph.first_focusable_within(scope, true))
3030            .map(FocusRequest::Focus)
3031            .unwrap_or(FocusRequest::Clear)
3032    }
3033
3034    fn apply_pending_overlay_focus(&mut self, invalidations: &mut Vec<InvalidationRequest>) {
3035        let Some(request) = self.pending_overlay_focus.take() else {
3036            return;
3037        };
3038        let effects = self.apply_focus_request(request);
3039        self.apply_event_effects(effects, invalidations);
3040    }
3041
3042    fn focus_transition_invalidations(&self, widget_id: WidgetId) -> Vec<InvalidationRequest> {
3043        let mut invalidations = vec![InvalidationRequest::new(
3044            InvalidationTarget::Widget(widget_id),
3045            InvalidationKind::Semantics,
3046        )];
3047
3048        if let Some(node) = self.graph.node(widget_id) {
3049            invalidations.push(
3050                InvalidationRequest::new(
3051                    InvalidationTarget::Widget(widget_id),
3052                    InvalidationKind::Paint,
3053                )
3054                .with_region(node.geometry.paint_bounds),
3055            );
3056        }
3057
3058        invalidations
3059    }
3060
3061    fn render(
3062        &mut self,
3063        text_system: Arc<TextSystem>,
3064        font_registry: Arc<FontRegistry>,
3065        image_registry: Arc<ImageRegistry>,
3066    ) -> RenderOutput {
3067        let diagnostics_enabled = window_scene_statistics_detail_mode(self.id).is_detailed();
3068        let mut diagnostics = RenderDiagnostics::default();
3069        let mut invalidations = std::mem::take(&mut self.pending_invalidations);
3070        let mut repainted = false;
3071        let mut repaint_layers = Vec::new();
3072        let mut dirty_layers = Vec::new();
3073        let mut layer_updates = Vec::new();
3074        let previous_graph =
3075            if (self.schedule.measure || self.schedule.arrange) && !self.graph.is_empty() {
3076                Some(self.graph.snapshot())
3077            } else {
3078                None
3079            };
3080        let mut graph_changes = GraphChangeSet::default();
3081
3082        if self.last_frame.is_none() {
3083            self.schedule = FrameSchedule::bootstrap();
3084        }
3085
3086        if self.schedule.measure || self.schedule.arrange || self.viewport.is_none() {
3087            let started = Instant::now();
3088            let pass_invalidations = self.run_measure_arrange_pass(
3089                &invalidations,
3090                Arc::clone(&text_system),
3091                Arc::clone(&font_registry),
3092                Arc::clone(&image_registry),
3093            );
3094            self.schedule.extend(&pass_invalidations);
3095            invalidations.extend(pass_invalidations);
3096            graph_changes = self.collect_graph_changes(previous_graph.as_ref());
3097            if diagnostics_enabled {
3098                diagnostics.push(FramePhase::MeasureArrange, started.elapsed());
3099            }
3100        } else if self.schedule.hit_test || self.graph.is_empty() {
3101            let started = Instant::now();
3102            self.refresh_graph();
3103            if diagnostics_enabled {
3104                diagnostics.push(FramePhase::HitTest, started.elapsed());
3105            }
3106        }
3107
3108        self.apply_pending_overlay_focus(&mut invalidations);
3109
3110        let viewport = self.viewport.unwrap_or(Size::ZERO);
3111        let dpi_info = self.dpi_info_for_viewport(viewport);
3112        let previous_scene = self.last_frame.as_ref().map(|frame| &frame.scene);
3113        let mut composition_only_transforms = self
3114            .select_composition_only_transforms(previous_scene, &graph_changes.transform_widgets);
3115        for translation in
3116            self.select_explicit_transform_translations(previous_scene, &invalidations)
3117        {
3118            if composition_only_transforms
3119                .iter()
3120                .all(|existing| existing.widget_id != translation.widget_id)
3121            {
3122                composition_only_transforms.push(translation);
3123            }
3124        }
3125        let previous_scene_for_refresh = self.last_frame.as_ref().map(|frame| frame.scene.clone());
3126        let layer_descriptor_refreshes = self.collect_explicit_layer_descriptor_refreshes(
3127            previous_scene_for_refresh.as_ref(),
3128            &invalidations,
3129        );
3130        let composition_only_transform_ids = composition_only_transforms
3131            .iter()
3132            .map(|translation| translation.widget_id)
3133            .collect::<HashSet<_>>();
3134        let mut repaint_graph_widgets = graph_changes.repaint_widgets.clone();
3135        for translation in &graph_changes.transform_widgets {
3136            if !composition_only_transform_ids.contains(&translation.widget_id) {
3137                repaint_graph_widgets.push(translation.widget_id);
3138            }
3139        }
3140
3141        if self.schedule.paint || self.last_frame.is_none() || !repaint_graph_widgets.is_empty() {
3142            repaint_layers = self.collect_dirty_layers(&invalidations);
3143            dirty_layers = repaint_layers.clone();
3144            for widget_id in repaint_graph_widgets.iter().copied() {
3145                if self.graph.contains(widget_id) && !dirty_layers.contains(&widget_id) {
3146                    dirty_layers.push(widget_id);
3147                }
3148                if self.graph.contains(widget_id) && !repaint_layers.contains(&widget_id) {
3149                    repaint_layers.push(widget_id);
3150                }
3151            }
3152
3153            // A freshly repainted descendant is already painted at its new
3154            // absolute bounds. Translating its retained ancestor afterward
3155            // would move that replacement twice, so promote the mixed update
3156            // to a content repaint of the retained ancestor.
3157            let mixed_update_roots = composition_only_transforms
3158                .iter()
3159                .filter(|translation| {
3160                    dirty_layers.iter().any(|dirty_widget| {
3161                        self.widget_is_ancestor_of(translation.widget_id, *dirty_widget)
3162                    })
3163                })
3164                .map(|translation| translation.widget_id)
3165                .collect::<Vec<_>>();
3166            repaint_layers.extend(mixed_update_roots.iter().copied());
3167            dirty_layers.extend(mixed_update_roots);
3168            self.minimize_layer_roots(&mut repaint_layers);
3169            self.minimize_layer_roots(&mut dirty_layers);
3170
3171            composition_only_transforms.retain(|translation| {
3172                !dirty_layers.iter().any(|dirty_widget| {
3173                    *dirty_widget == translation.widget_id
3174                        || self.widget_is_ancestor_of(*dirty_widget, translation.widget_id)
3175                })
3176            });
3177        }
3178
3179        let mut scene_changed = false;
3180        let has_ordering_updates = invalidations
3181            .iter()
3182            .any(|request| request.kind == InvalidationKind::Ordering);
3183        if self.last_frame.is_none()
3184            || !repaint_layers.is_empty()
3185            || !composition_only_transforms.is_empty()
3186            || !layer_descriptor_refreshes.is_empty()
3187            || has_ordering_updates
3188        {
3189            let started = Instant::now();
3190            repainted = self.last_frame.is_none() || !repaint_layers.is_empty();
3191            scene_changed = true;
3192
3193            let focused_path = self
3194                .focus
3195                .focused_widget
3196                .and_then(|widget_id| self.graph.path_to(widget_id));
3197            let preserve_ime = focused_path.as_ref().is_none_or(|path| {
3198                !repaint_layers
3199                    .iter()
3200                    .any(|widget_id| path.iter().any(|candidate| candidate == widget_id))
3201            });
3202            let baseline_ime_composition_rect = if preserve_ime {
3203                self.ime_composition_rect
3204            } else {
3205                None
3206            };
3207
3208            let (
3209                scene,
3210                paint_images,
3211                mut paint_bounds_by_widget,
3212                paint_invalidations,
3213                mut ime_composition_rect,
3214            ) = if self.last_frame.is_none() || repaint_layers.contains(&self.root.id()) {
3215                self.paint_full_scene(
3216                    dpi_info,
3217                    Arc::clone(&text_system),
3218                    Arc::clone(&font_registry),
3219                    Arc::clone(&image_registry),
3220                )
3221            } else if repaint_layers.is_empty() {
3222                (
3223                    self.last_frame
3224                        .as_ref()
3225                        .map(|frame| frame.scene.clone())
3226                        .unwrap_or_default(),
3227                    Vec::new(),
3228                    self.last_paint_bounds_by_widget.clone(),
3229                    Vec::new(),
3230                    baseline_ime_composition_rect,
3231                )
3232            } else {
3233                self.repaint_dirty_layers(
3234                    dpi_info,
3235                    &repaint_layers,
3236                    baseline_ime_composition_rect,
3237                    Arc::clone(&text_system),
3238                    Arc::clone(&font_registry),
3239                    Arc::clone(&image_registry),
3240                )
3241            };
3242            let mut scene = scene;
3243            for translation in &composition_only_transforms {
3244                let _ = scene.translate_layer(translation.widget_id, translation.delta);
3245                for widget_id in self.graph.subtree_ids(translation.widget_id) {
3246                    if let Some(bounds) = paint_bounds_by_widget.get_mut(&widget_id) {
3247                        *bounds = bounds.translate(translation.delta);
3248                    }
3249                }
3250                if let Some(moved_bounds) =
3251                    paint_bounds_by_widget.get(&translation.widget_id).copied()
3252                {
3253                    // Flat ancestors can derive their paint bounds from this
3254                    // explicit child. Without repainting we cannot separate an
3255                    // ancestor's own ink from its old child contribution, so
3256                    // conservatively include the moved bounds. This prevents
3257                    // later damage from missing the child's new location.
3258                    let mut ancestor = self
3259                        .graph
3260                        .node(translation.widget_id)
3261                        .and_then(|node| node.parent);
3262                    while let Some(widget_id) = ancestor {
3263                        paint_bounds_by_widget
3264                            .entry(widget_id)
3265                            .and_modify(|bounds| *bounds = bounds.union(moved_bounds))
3266                            .or_insert(moved_bounds);
3267                        ancestor = self.graph.node(widget_id).and_then(|node| node.parent);
3268                    }
3269                }
3270                if focused_path
3271                    .as_ref()
3272                    .is_some_and(|path| path.contains(&translation.widget_id))
3273                {
3274                    ime_composition_rect =
3275                        ime_composition_rect.map(|rect| rect.translate(translation.delta));
3276                }
3277            }
3278            for refresh in &layer_descriptor_refreshes {
3279                let _ =
3280                    scene.replace_layer_descriptor(refresh.widget_id, refresh.descriptor.clone());
3281            }
3282            self.sync_scene_stack_metadata(&mut scene);
3283            self.last_paint_bounds_by_widget = paint_bounds_by_widget;
3284            self.graph
3285                .update_paint_bounds_from_snapshot(&self.last_paint_bounds_by_widget);
3286            invalidations.extend(paint_invalidations);
3287            self.ime_composition_rect = ime_composition_rect;
3288            let previous_scene = self.last_frame.as_ref().map(|frame| &frame.scene);
3289            layer_updates = self.collect_layer_updates(
3290                previous_scene,
3291                &scene,
3292                &invalidations,
3293                &dirty_layers,
3294                &composition_only_transforms
3295                    .iter()
3296                    .map(|translation| translation.widget_id)
3297                    .collect::<Vec<_>>(),
3298            );
3299            let frame_image_registry =
3300                self.frame_image_registry(Arc::clone(&image_registry), paint_images);
3301            retain_text_layouts_for_scene(text_system.as_ref(), &scene);
3302            self.last_frame = Some(SceneFrame {
3303                window_id: self.id,
3304                viewport,
3305                surface_size: dpi_info.surface_size,
3306                scale_factor: dpi_info.scale_factor,
3307                dirty_regions: Vec::new(),
3308                layer_updates: layer_updates.clone(),
3309                scene,
3310                font_registry: Arc::clone(&font_registry),
3311                image_registry: frame_image_registry,
3312                text_layout_registry: text_system.text_layout_registry(),
3313            });
3314            if diagnostics_enabled && repainted {
3315                diagnostics.push(FramePhase::Paint, started.elapsed());
3316            }
3317        }
3318
3319        if self.schedule.semantics || self.last_semantics.is_empty() {
3320            let started = Instant::now();
3321            let mut semantics_ctx = SemanticsCtx::new(
3322                self.id,
3323                self.root.id(),
3324                self.root.id(),
3325                self.root.bounds(),
3326                self.focus.focused_widget,
3327            );
3328            self.root.semantics(&mut semantics_ctx);
3329            let semantics = self.assemble_semantics_tree(semantics_ctx.into_nodes());
3330            self.last_semantics = self.filter_modal_semantics(semantics);
3331            if diagnostics_enabled {
3332                diagnostics.push(FramePhase::Semantics, started.elapsed());
3333            }
3334        }
3335
3336        let viewport_rect = Rect::from_origin_size(Point::ZERO, viewport);
3337        let dirty_regions = collect_dirty_regions(viewport, &invalidations, repainted, |request| {
3338            self.default_dirty_region_for_request(viewport_rect, request)
3339        });
3340        let mut frame = self
3341            .last_frame
3342            .clone()
3343            .unwrap_or_else(|| SceneFrame::new(self.id, viewport));
3344        frame.viewport = viewport;
3345        frame.surface_size = dpi_info.surface_size;
3346        frame.scale_factor = dpi_info.scale_factor;
3347        frame.dirty_regions = dirty_regions;
3348        frame.layer_updates = if scene_changed {
3349            layer_updates
3350        } else {
3351            self.collect_layer_updates(
3352                self.last_frame.as_ref().map(|stored| &stored.scene),
3353                &frame.scene,
3354                &invalidations,
3355                &[],
3356                &composition_only_transforms
3357                    .iter()
3358                    .map(|translation| translation.widget_id)
3359                    .collect::<Vec<_>>(),
3360            )
3361        };
3362        frame.font_registry = font_registry;
3363        frame.image_registry = self.frame_image_registry(image_registry, Vec::new());
3364
3365        if diagnostics_enabled {
3366            let layout_cache = text_system.layout_cache_snapshot();
3367            diagnostics.text_caches.runtime_layout =
3368                CacheMetrics::new(layout_cache.entries, layout_cache.hits, layout_cache.misses);
3369        }
3370
3371        diagnostics.widget_count = self.graph.nodes.len();
3372        diagnostics.runtime_text_timing = sui_text::take_text_timing_collection();
3373        diagnostics.widget_timings = diagnostics::take_widget_timing_collection();
3374        diagnostics.reactive_invalidations = std::mem::take(&mut self.pending_reactive_diagnostics);
3375        diagnostics.command_dispatches = std::mem::take(&mut self.pending_command_diagnostics);
3376        diagnostics.invalidations = std::mem::take(&mut self.pending_invalidation_diagnostics);
3377        diagnostics.widget_rebuilds = diagnostics::take_widget_rebuilds(self.id);
3378        diagnostics.active_animated_widget_count = self.active_animated_widget_count();
3379        diagnostics.animation_frame_wake_count = self.pending_animation_wake_count;
3380        diagnostics.animation_repaint_frame_count =
3381            usize::from(self.pending_animation_wake_count > 0 && repainted);
3382        diagnostics.animation_transform_effect_only_frame_count = usize::from(
3383            self.pending_animation_wake_count > 0
3384                && self.animation_frame_is_transform_only(repainted, &frame.layer_updates),
3385        );
3386        self.pending_animation_wake_count = 0;
3387
3388        self.capture_inspector_diagnostics(&diagnostics);
3389
3390        self.schedule.clear();
3391
3392        RenderOutput {
3393            title: self.title.clone(),
3394            frame,
3395            semantics: self.last_semantics.clone(),
3396            ime_composition_rect: self.ime_composition_rect,
3397            diagnostics,
3398        }
3399    }
3400
3401    fn frame_image_registry(
3402        &self,
3403        base: Arc<ImageRegistry>,
3404        paint_images: Vec<(ImageHandle, PaintImageResource)>,
3405    ) -> Arc<ImageRegistry> {
3406        let mut registry = self
3407            .last_frame
3408            .as_ref()
3409            .map(|frame| frame.image_registry.as_ref().clone())
3410            .unwrap_or_else(|| base.as_ref().clone());
3411        for (handle, image) in base.iter() {
3412            registry.insert(handle, image.clone());
3413        }
3414        for (handle, image) in base.iter_external() {
3415            registry.insert_external(handle, *image);
3416        }
3417        for (handle, image) in paint_images {
3418            match image {
3419                PaintImageResource::Cpu(image) => {
3420                    registry.insert(handle, image);
3421                }
3422                PaintImageResource::External(image) => {
3423                    registry.insert_external(handle, image);
3424                }
3425            }
3426        }
3427        Arc::new(registry)
3428    }
3429
3430    fn paint_full_scene(
3431        &mut self,
3432        dpi_info: DpiInfo,
3433        text_system: Arc<TextSystem>,
3434        font_registry: Arc<FontRegistry>,
3435        image_registry: Arc<ImageRegistry>,
3436    ) -> PaintOutput {
3437        let mut paint_ctx = PaintCtx::new(
3438            self.id,
3439            self.root.id(),
3440            self.root.bounds(),
3441            self.focus.focused_widget,
3442            dpi_info,
3443            text_system,
3444            font_registry,
3445            self.last_frame
3446                .as_ref()
3447                .map(|frame| Arc::clone(&frame.image_registry))
3448                .unwrap_or(image_registry),
3449        );
3450        let _ = self
3451            .root
3452            .paint_layer_contents_for(self.root.id(), &mut paint_ctx);
3453        paint_ctx.into_parts()
3454    }
3455
3456    fn repaint_dirty_layers(
3457        &mut self,
3458        dpi_info: DpiInfo,
3459        dirty_layers: &[WidgetId],
3460        baseline_ime_composition_rect: Option<Rect>,
3461        text_system: Arc<TextSystem>,
3462        font_registry: Arc<FontRegistry>,
3463        image_registry: Arc<ImageRegistry>,
3464    ) -> PaintOutput {
3465        let mut scene = self
3466            .last_frame
3467            .as_ref()
3468            .map(|frame| frame.scene.clone())
3469            .unwrap_or_default();
3470        let mut images = Vec::new();
3471        let mut invalidations = Vec::new();
3472        let mut paint_bounds_by_widget = self.last_paint_bounds_by_widget.clone();
3473        let mut ime_composition_rect = baseline_ime_composition_rect;
3474
3475        for &widget_id in dirty_layers {
3476            let Some(bounds) = self
3477                .graph
3478                .node(widget_id)
3479                .map(|node| node.geometry.layout_bounds)
3480            else {
3481                return self.paint_full_scene(dpi_info, text_system, font_registry, image_registry);
3482            };
3483
3484            let mut paint_ctx = PaintCtx::new(
3485                self.id,
3486                widget_id,
3487                bounds,
3488                self.focus.focused_widget,
3489                dpi_info,
3490                Arc::clone(&text_system),
3491                Arc::clone(&font_registry),
3492                self.last_frame
3493                    .as_ref()
3494                    .map(|frame| Arc::clone(&frame.image_registry))
3495                    .unwrap_or_else(|| Arc::clone(&image_registry)),
3496            );
3497            if !self
3498                .root
3499                .paint_layer_contents_for(widget_id, &mut paint_ctx)
3500            {
3501                return self.paint_full_scene(dpi_info, text_system, font_registry, image_registry);
3502            }
3503
3504            let (
3505                layer_scene,
3506                layer_images,
3507                layer_paint_bounds,
3508                layer_invalidations,
3509                layer_ime_composition_rect,
3510            ) = paint_ctx.into_parts();
3511            let Some(descriptor) = self.root.layer_descriptor_for(widget_id, &layer_scene) else {
3512                return self.paint_full_scene(dpi_info, text_system, font_registry, image_registry);
3513            };
3514            if widget_id == self.root.id()
3515                || !scene.replace_layer(
3516                    widget_id,
3517                    SceneLayer::from_descriptor(descriptor, layer_scene),
3518                )
3519            {
3520                return self.paint_full_scene(dpi_info, text_system, font_registry, image_registry);
3521            }
3522
3523            images.extend(layer_images);
3524            paint_bounds_by_widget.extend(layer_paint_bounds);
3525            invalidations.extend(layer_invalidations);
3526            if layer_ime_composition_rect.is_some() {
3527                ime_composition_rect = layer_ime_composition_rect;
3528            }
3529        }
3530
3531        (
3532            scene,
3533            images,
3534            paint_bounds_by_widget,
3535            invalidations,
3536            ime_composition_rect,
3537        )
3538    }
3539
3540    fn collect_dirty_layers(&self, invalidations: &[InvalidationRequest]) -> Vec<WidgetId> {
3541        let candidates: HashSet<WidgetId> = invalidations
3542            .iter()
3543            .filter(|request| {
3544                matches!(
3545                    request.kind,
3546                    InvalidationKind::Measure
3547                        | InvalidationKind::Clip
3548                        | InvalidationKind::Visibility
3549                        | InvalidationKind::Paint
3550                        | InvalidationKind::Text
3551                        | InvalidationKind::Resources
3552                )
3553            })
3554            .map(|request| match request.target {
3555                InvalidationTarget::Widget(widget_id) if self.graph.contains(widget_id) => self
3556                    .graph
3557                    .nearest_paint_boundary_ancestor_or_root(widget_id),
3558                InvalidationTarget::Widget(_) => self.root.id(),
3559                InvalidationTarget::Window(_) | InvalidationTarget::Surface(_) => self.root.id(),
3560            })
3561            .collect();
3562
3563        if self.last_frame.is_none() || candidates.contains(&self.root.id()) {
3564            return vec![self.root.id()];
3565        }
3566
3567        let mut candidates: Vec<_> = candidates
3568            .into_iter()
3569            .filter(|widget_id| self.graph.contains(*widget_id))
3570            .collect();
3571        candidates.sort_by_key(|widget_id| {
3572            self.graph
3573                .path_to(*widget_id)
3574                .map_or(usize::MAX, |path| path.len())
3575        });
3576
3577        let mut minimized = Vec::new();
3578        for widget_id in candidates {
3579            if minimized
3580                .iter()
3581                .any(|ancestor| self.widget_is_ancestor_of(*ancestor, widget_id))
3582            {
3583                continue;
3584            }
3585            minimized.push(widget_id);
3586        }
3587
3588        minimized
3589    }
3590
3591    fn collect_graph_changes(&self, previous: Option<&WidgetGraphSnapshot>) -> GraphChangeSet {
3592        let Some(previous) = previous else {
3593            return GraphChangeSet {
3594                repaint_widgets: vec![self.graph.root],
3595                transform_widgets: Vec::new(),
3596            };
3597        };
3598
3599        let current_snapshot = self.graph.snapshot();
3600        let previous_nodes: HashMap<_, _> =
3601            previous.nodes.iter().map(|node| (node.id, node)).collect();
3602        let current_nodes: HashMap<_, _> = current_snapshot
3603            .nodes
3604            .iter()
3605            .map(|node| (node.id, node))
3606            .collect();
3607        let widget_ids = previous_nodes
3608            .keys()
3609            .chain(current_nodes.keys())
3610            .copied()
3611            .collect::<HashSet<_>>();
3612        let mut repaint_candidates = HashSet::new();
3613        let mut transform_candidates = Vec::new();
3614
3615        for widget_id in widget_ids {
3616            match (
3617                previous_nodes.get(&widget_id),
3618                current_nodes.get(&widget_id),
3619            ) {
3620                (Some(previous_node), Some(current_node)) => {
3621                    if previous_node.measured_size != current_node.measured_size
3622                        || previous_node.geometry.layout_bounds.size
3623                            != current_node.geometry.layout_bounds.size
3624                        || previous_node.parent != current_node.parent
3625                        || previous_node.children != current_node.children
3626                    {
3627                        repaint_candidates.insert(resolve_snapshot_paint_boundary_or_root(
3628                            &current_snapshot,
3629                            current_node.id,
3630                        ));
3631                        continue;
3632                    }
3633
3634                    let delta = current_node.geometry.layout_bounds.origin
3635                        - previous_node.geometry.layout_bounds.origin;
3636                    if delta != Vector::ZERO {
3637                        let resolved_boundary = resolve_snapshot_paint_boundary_or_root(
3638                            &current_snapshot,
3639                            current_node.id,
3640                        );
3641                        if resolved_boundary == current_node.id
3642                            && current_node.paint_boundary == PaintBoundaryMode::Explicit
3643                        {
3644                            transform_candidates.push(LayerTranslation {
3645                                widget_id: current_node.id,
3646                                delta,
3647                            });
3648                        } else if current_nodes
3649                            .get(&resolved_boundary)
3650                            .zip(previous_nodes.get(&resolved_boundary))
3651                            .is_some_and(|(current_boundary, previous_boundary)| {
3652                                current_boundary.paint_boundary == PaintBoundaryMode::Explicit
3653                                    && current_boundary.geometry.layout_bounds.origin
3654                                        - previous_boundary.geometry.layout_bounds.origin
3655                                        == delta
3656                            })
3657                        {
3658                            // A descendant that moved by exactly the same delta as its
3659                            // explicit paint boundary is covered by that boundary's
3660                            // composition-only transform. Treating each flat descendant
3661                            // as an independent move would unnecessarily repaint the layer.
3662                        } else {
3663                            repaint_candidates.insert(resolved_boundary);
3664                        }
3665                    }
3666                }
3667                (None, Some(current_node)) => {
3668                    repaint_candidates.insert(resolve_snapshot_paint_boundary_or_root(
3669                        &current_snapshot,
3670                        current_node.id,
3671                    ));
3672                }
3673                (Some(previous_node), None) => {
3674                    repaint_candidates.insert(resolve_snapshot_paint_boundary_or_root(
3675                        previous,
3676                        previous_node.id,
3677                    ));
3678                }
3679                (None, None) => {}
3680            }
3681        }
3682
3683        let mut repaint_widgets = repaint_candidates.into_iter().collect::<Vec<_>>();
3684        repaint_widgets.sort_by_key(|widget_id| self.widget_depth(*widget_id));
3685        let mut minimized_repaint = Vec::new();
3686        for widget_id in repaint_widgets {
3687            if minimized_repaint
3688                .iter()
3689                .any(|ancestor| self.widget_is_ancestor_of(*ancestor, widget_id))
3690            {
3691                continue;
3692            }
3693            minimized_repaint.push(widget_id);
3694        }
3695
3696        transform_candidates.sort_by_key(|translation| self.widget_depth(translation.widget_id));
3697        let mut minimized_transforms = Vec::new();
3698        for candidate in transform_candidates {
3699            if minimized_repaint
3700                .iter()
3701                .any(|ancestor| self.widget_is_ancestor_of(*ancestor, candidate.widget_id))
3702            {
3703                continue;
3704            }
3705
3706            let inherited_delta = minimized_transforms
3707                .iter()
3708                .filter(|translation: &&LayerTranslation| {
3709                    self.widget_is_ancestor_of(translation.widget_id, candidate.widget_id)
3710                })
3711                .fold(Vector::ZERO, |current, translation| {
3712                    current + translation.delta
3713                });
3714            let residual = candidate.delta - inherited_delta;
3715            if residual == Vector::ZERO {
3716                continue;
3717            }
3718
3719            minimized_transforms.push(LayerTranslation {
3720                widget_id: candidate.widget_id,
3721                delta: residual,
3722            });
3723        }
3724
3725        GraphChangeSet {
3726            repaint_widgets: minimized_repaint,
3727            transform_widgets: minimized_transforms,
3728        }
3729    }
3730
3731    fn select_composition_only_transforms(
3732        &self,
3733        previous_scene: Option<&Scene>,
3734        transform_widgets: &[LayerTranslation],
3735    ) -> Vec<LayerTranslation> {
3736        let previous_layers = previous_scene.map(collect_scene_layers).unwrap_or_default();
3737        transform_widgets
3738            .iter()
3739            .copied()
3740            .filter(|translation| previous_layers.contains_key(&translation.widget_id))
3741            .collect()
3742    }
3743
3744    fn select_explicit_transform_translations(
3745        &self,
3746        previous_scene: Option<&Scene>,
3747        invalidations: &[InvalidationRequest],
3748    ) -> Vec<LayerTranslation> {
3749        let previous_layers = previous_scene.map(collect_scene_layers).unwrap_or_default();
3750        let mut translations = Vec::new();
3751
3752        for request in invalidations {
3753            if request.kind != InvalidationKind::Transform {
3754                continue;
3755            }
3756
3757            let InvalidationTarget::Widget(widget_id) = request.target else {
3758                continue;
3759            };
3760            let resolved_boundary = self
3761                .graph
3762                .nearest_paint_boundary_ancestor_or_root(widget_id);
3763            if resolved_boundary == self.root.id() {
3764                continue;
3765            }
3766            let Some(previous) = previous_layers.get(&resolved_boundary) else {
3767                continue;
3768            };
3769            let Some(current) = self.graph.node(resolved_boundary) else {
3770                continue;
3771            };
3772
3773            let delta = current.geometry.layout_bounds.origin - previous.bounds.origin;
3774            if delta == Vector::ZERO {
3775                continue;
3776            }
3777
3778            if translations
3779                .iter()
3780                .all(|translation: &LayerTranslation| translation.widget_id != resolved_boundary)
3781            {
3782                translations.push(LayerTranslation {
3783                    widget_id: resolved_boundary,
3784                    delta,
3785                });
3786            }
3787        }
3788
3789        translations
3790    }
3791
3792    fn collect_explicit_layer_descriptor_refreshes(
3793        &mut self,
3794        previous_scene: Option<&Scene>,
3795        invalidations: &[InvalidationRequest],
3796    ) -> Vec<LayerDescriptorRefresh> {
3797        let Some(previous_scene) = previous_scene else {
3798            return Vec::new();
3799        };
3800        if !invalidations.iter().any(|request| {
3801            matches!(
3802                request.kind,
3803                InvalidationKind::Transform | InvalidationKind::Effect
3804            )
3805        }) {
3806            return Vec::new();
3807        }
3808
3809        let previous_layers = collect_scene_layers(previous_scene);
3810        let mut refreshes = Vec::new();
3811
3812        for (widget_id, previous_descriptor) in previous_layers {
3813            let Some(layer_scene) = previous_scene.layer_scene(widget_id).cloned() else {
3814                continue;
3815            };
3816            let Some(descriptor) = self.root.layer_descriptor_for(widget_id, &layer_scene) else {
3817                continue;
3818            };
3819            if descriptor.properties == previous_descriptor.properties {
3820                continue;
3821            }
3822            refreshes.push(LayerDescriptorRefresh {
3823                widget_id,
3824                descriptor,
3825            });
3826        }
3827
3828        refreshes
3829    }
3830
3831    fn widget_depth(&self, widget_id: WidgetId) -> usize {
3832        self.graph.depth(widget_id).unwrap_or(usize::MAX)
3833    }
3834
3835    fn minimize_layer_roots(&self, candidates: &mut Vec<WidgetId>) {
3836        candidates.sort_by_key(|widget_id| (self.widget_depth(*widget_id), widget_id.get()));
3837        candidates.dedup();
3838        let mut minimized = Vec::with_capacity(candidates.len());
3839        for widget_id in candidates.iter().copied() {
3840            if minimized
3841                .iter()
3842                .any(|ancestor| self.widget_is_ancestor_of(*ancestor, widget_id))
3843            {
3844                continue;
3845            }
3846            minimized.push(widget_id);
3847        }
3848        *candidates = minimized;
3849    }
3850
3851    fn default_dirty_region_for_request(
3852        &self,
3853        viewport_rect: Rect,
3854        request: &InvalidationRequest,
3855    ) -> Rect {
3856        match request.target {
3857            InvalidationTarget::Widget(widget_id) => self
3858                .graph
3859                .node(widget_id)
3860                .map(|node| node.geometry.paint_bounds)
3861                .unwrap_or(viewport_rect),
3862            InvalidationTarget::Window(_) | InvalidationTarget::Surface(_) => viewport_rect,
3863        }
3864    }
3865
3866    fn collect_layer_updates(
3867        &self,
3868        previous_scene: Option<&Scene>,
3869        scene: &Scene,
3870        invalidations: &[InvalidationRequest],
3871        dirty_layers: &[WidgetId],
3872        graph_dirty_widgets: &[WidgetId],
3873    ) -> Vec<SceneLayerUpdate> {
3874        let current_layers = collect_scene_layers(scene);
3875        if current_layers.is_empty() {
3876            return Vec::new();
3877        }
3878
3879        let previous_layers = previous_scene.map(collect_scene_layers).unwrap_or_default();
3880        let mut updates = HashMap::<WidgetId, SceneLayerUpdateKind>::new();
3881        let mut damage_regions = HashMap::<WidgetId, Rect>::new();
3882        let explicit_transform_widgets = invalidations
3883            .iter()
3884            .filter_map(|request| {
3885                if request.kind != InvalidationKind::Transform {
3886                    return None;
3887                }
3888
3889                match request.target {
3890                    InvalidationTarget::Widget(widget_id) if self.graph.contains(widget_id) => {
3891                        Some(
3892                            self.graph
3893                                .nearest_paint_boundary_ancestor_or_root(widget_id),
3894                        )
3895                    }
3896                    _ => None,
3897                }
3898            })
3899            .collect::<HashSet<_>>();
3900
3901        for request in invalidations {
3902            let Some(kind) = invalidation_to_layer_update_kind(request.kind) else {
3903                continue;
3904            };
3905            let widget_id = match request.target {
3906                InvalidationTarget::Widget(widget_id) if self.graph.contains(widget_id) => self
3907                    .graph
3908                    .nearest_paint_boundary_ancestor_or_root(widget_id),
3909                InvalidationTarget::Widget(_) => self.root.id(),
3910                InvalidationTarget::Window(_) | InvalidationTarget::Surface(_) => self.root.id(),
3911            };
3912            if request.kind == InvalidationKind::Arrange
3913                && explicit_transform_widgets
3914                    .iter()
3915                    .any(|candidate| self.widget_is_ancestor_of(widget_id, *candidate))
3916            {
3917                continue;
3918            }
3919            merge_layer_update_kind(&mut updates, widget_id, kind);
3920            if let Some(region) = request.region {
3921                damage_regions
3922                    .entry(widget_id)
3923                    .and_modify(|current| *current = current.union(region))
3924                    .or_insert(region);
3925            }
3926        }
3927
3928        for (widget_id, descriptor) in &current_layers {
3929            let Some(previous) = previous_layers.get(widget_id) else {
3930                merge_layer_update_kind(&mut updates, *widget_id, SceneLayerUpdateKind::Content);
3931                continue;
3932            };
3933            if descriptor.stack_host != previous.stack_host
3934                || descriptor.stack_order != previous.stack_order
3935                || descriptor.transient_owner_surface != previous.transient_owner_surface
3936                || descriptor.is_stack_surface != previous.is_stack_surface
3937            {
3938                merge_layer_update_kind(&mut updates, *widget_id, SceneLayerUpdateKind::Ordering);
3939            }
3940            if descriptor.properties.translation != previous.properties.translation {
3941                merge_layer_update_kind(&mut updates, *widget_id, SceneLayerUpdateKind::Transform);
3942            }
3943            if descriptor.properties.opacity != previous.properties.opacity {
3944                merge_layer_update_kind(&mut updates, *widget_id, SceneLayerUpdateKind::Effect);
3945            }
3946        }
3947
3948        for widget_id in graph_dirty_widgets.iter().copied() {
3949            merge_layer_update_kind(&mut updates, widget_id, SceneLayerUpdateKind::Transform);
3950        }
3951
3952        for widget_id in dirty_layers.iter().copied() {
3953            merge_layer_update_kind(&mut updates, widget_id, SceneLayerUpdateKind::Content);
3954        }
3955
3956        let mut resolved_updates = Vec::new();
3957        for (widget_id, kind) in updates {
3958            let Some(descriptor) = current_layers.get(&widget_id).cloned() else {
3959                continue;
3960            };
3961            let fallback_damage = previous_layers
3962                .get(&widget_id)
3963                .map(|previous| {
3964                    previous
3965                        .presented_paint_bounds()
3966                        .union(descriptor.presented_paint_bounds())
3967                })
3968                .unwrap_or(descriptor.presented_paint_bounds());
3969            let damage = damage_regions
3970                .get(&widget_id)
3971                .copied()
3972                .unwrap_or(fallback_damage);
3973            resolved_updates
3974                .push(SceneLayerUpdate::from_descriptor(kind, descriptor).with_damage(damage));
3975        }
3976
3977        resolved_updates.sort_by_key(|update| update.owner.get());
3978        resolved_updates
3979    }
3980
3981    fn widget_is_ancestor_of(&self, ancestor: WidgetId, widget_id: WidgetId) -> bool {
3982        self.graph.is_ancestor_of(ancestor, widget_id)
3983    }
3984
3985    /// Build the measure scope for this pass from the pending invalidations.
3986    ///
3987    /// Measure/Text/Visibility/Ordering invalidations targeting a widget that is
3988    /// in the current graph define the changed subtrees; their ancestor paths
3989    /// must also re-measure. Anything that cannot be resolved to concrete widgets
3990    /// (non-widget targets, widgets missing from the graph, or no relevant
3991    /// invalidation at all) falls back to re-measuring everything, which is always
3992    /// correct.
3993    fn build_measure_scope(&self, invalidations: &[InvalidationRequest]) -> Rc<MeasureScope> {
3994        let mut subtree_roots: HashSet<WidgetId> = HashSet::new();
3995        let mut force_all = false;
3996        for request in invalidations {
3997            if !matches!(
3998                request.kind,
3999                InvalidationKind::Measure
4000                    | InvalidationKind::Text
4001                    | InvalidationKind::Visibility
4002                    | InvalidationKind::Ordering
4003            ) {
4004                continue;
4005            }
4006            match request.target {
4007                InvalidationTarget::Widget(widget_id) => {
4008                    subtree_roots.insert(widget_id);
4009                }
4010                InvalidationTarget::Window(_) | InvalidationTarget::Surface(_) => {
4011                    force_all = true;
4012                }
4013            }
4014        }
4015
4016        if force_all || subtree_roots.is_empty() {
4017            return Rc::new(MeasureScope::force_all());
4018        }
4019
4020        let mut dirty: HashSet<WidgetId> = HashSet::new();
4021        for widget_id in &subtree_roots {
4022            if !self.graph.extend_ancestors(*widget_id, &mut dirty) {
4023                return Rc::new(MeasureScope::force_all());
4024            }
4025        }
4026
4027        Rc::new(MeasureScope::scoped(dirty, subtree_roots))
4028    }
4029
4030    fn run_measure_arrange_pass(
4031        &mut self,
4032        invalidations: &[InvalidationRequest],
4033        text_system: Arc<TextSystem>,
4034        font_registry: Arc<FontRegistry>,
4035        image_registry: Arc<ImageRegistry>,
4036    ) -> Vec<InvalidationRequest> {
4037        let constraints = self.measure_constraints();
4038        let scope = self.build_measure_scope(invalidations);
4039        let mut measure_ctx = MeasureCtx::new_scoped_at(
4040            self.id,
4041            self.root.id(),
4042            self.root.bounds(),
4043            self.current_dpi_info(),
4044            text_system,
4045            font_registry,
4046            image_registry,
4047            scope,
4048            self.last_tick_time,
4049        );
4050        let measured_root = if self.schedule.measure || self.viewport.is_none() {
4051            self.root.measure(&mut measure_ctx, constraints)
4052        } else {
4053            self.root.measured_size()
4054        };
4055        let viewport = constraints.clamp(measured_root);
4056
4057        let mut arrange_ctx = ArrangeCtx::new_at(
4058            self.id,
4059            self.root.id(),
4060            self.current_dpi_info(),
4061            self.last_tick_time,
4062        );
4063        self.root.arrange(
4064            &mut arrange_ctx,
4065            Rect::from_origin_size(Point::ZERO, viewport),
4066        );
4067        self.viewport = Some(viewport);
4068        self.schedule.measure = false;
4069        self.schedule.arrange = false;
4070        self.schedule.hit_test = false;
4071        self.refresh_graph();
4072
4073        let mut invalidations = measure_ctx.take_invalidations();
4074        self.apply_wake_requests(measure_ctx.take_wake_requests());
4075        invalidations.extend(arrange_ctx.take_invalidations());
4076        self.apply_wake_requests(arrange_ctx.take_wake_requests());
4077        invalidations
4078    }
4079
4080    fn refresh_graph(&mut self) {
4081        self.graph = WidgetGraph::rebuild(
4082            &self.root,
4083            self.focus.focused_widget,
4084            &self.last_paint_bounds_by_widget,
4085        );
4086        let overlay_focus = self.overlay_manager.sync(
4087            self.graph.overlay_snapshots(),
4088            &self.graph,
4089            self.focus.focused_widget,
4090        );
4091        if overlay_focus.is_some() {
4092            self.pending_overlay_focus = overlay_focus;
4093        }
4094        self.prune_runtime_state();
4095        self.schedule.hit_test = false;
4096    }
4097
4098    fn filter_modal_semantics(&self, mut nodes: Vec<SemanticsNode>) -> Vec<SemanticsNode> {
4099        let Some(modal) = self.overlay_manager.active_modal() else {
4100            return nodes;
4101        };
4102
4103        let modal_subtree = self
4104            .graph
4105            .subtree_ids(modal)
4106            .into_iter()
4107            .collect::<HashSet<_>>();
4108        let mut allowed = modal_subtree.clone();
4109        let mut ancestor = self.graph.node(modal).and_then(|node| node.parent);
4110        while let Some(widget_id) = ancestor {
4111            allowed.insert(widget_id);
4112            ancestor = self.graph.node(widget_id).and_then(|node| node.parent);
4113        }
4114
4115        let parents = nodes
4116            .iter()
4117            .map(|node| (node.id, node.parent))
4118            .collect::<HashMap<_, _>>();
4119        let belongs_to_modal = |node: &SemanticsNode| {
4120            if allowed.contains(&node.id) {
4121                return true;
4122            }
4123            let mut current = node.parent;
4124            let mut visited = HashSet::new();
4125            while let Some(parent) = current {
4126                if !visited.insert(parent) {
4127                    break;
4128                }
4129                if modal_subtree.contains(&parent) {
4130                    return true;
4131                }
4132                current = parents.get(&parent).copied().flatten();
4133            }
4134            false
4135        };
4136        nodes.retain(belongs_to_modal);
4137        if let Some(node) = nodes.iter_mut().find(|node| node.id == modal) {
4138            node.state.modal = true;
4139        }
4140        nodes
4141    }
4142
4143    fn sync_scene_stack_metadata(&self, scene: &mut Scene) {
4144        scene.visit_layers_mut(&mut |layer| {
4145            if let Some(node) = self.graph.node(layer.widget_id()) {
4146                layer.descriptor.stack_host = node.stack_host;
4147                layer.descriptor.stack_order = node.stack_surface_order;
4148                layer.descriptor.transient_owner_surface = node.transient_owner_surface;
4149                layer.descriptor.is_stack_surface = node.is_stack_surface;
4150                layer.descriptor.hit_test = node.hit_test;
4151            }
4152        });
4153        scene.reorder_stack_surfaces();
4154    }
4155
4156    fn prune_runtime_state(&mut self) {
4157        self.pointer_capture
4158            .retain(|_, widget_id| self.graph.contains(*widget_id));
4159        if self
4160            .active_drag
4161            .as_ref()
4162            .is_some_and(|drag| !self.graph.contains(drag.source))
4163        {
4164            self.active_drag = None;
4165        }
4166        self.scheduled_timers
4167            .retain(|timer| self.graph.contains(timer.target));
4168        self.delivering_timers
4169            .retain(|_, widget_id| self.graph.contains(*widget_id));
4170        self.async_wake_targets
4171            .retain(|_, widget_id| self.graph.contains(*widget_id));
4172        self.pending_async_wakeups
4173            .retain(|token| self.async_wake_targets.contains_key(token));
4174        self.requested_animation_frames
4175            .retain(|widget_id| self.graph.contains(*widget_id));
4176        self.delivering_animation_frames
4177            .retain(|widget_id| self.graph.contains(*widget_id));
4178        if self.requested_animation_frames.is_empty() && self.delivering_animation_frames.is_empty()
4179        {
4180            self.last_animation_frame_time = None;
4181        }
4182
4183        if self
4184            .focus
4185            .focused_widget
4186            .is_some_and(|widget_id| !self.graph.contains(widget_id))
4187        {
4188            self.focus.focused_widget = None;
4189            self.focused_semantics = None;
4190        }
4191    }
4192
4193    fn measure_constraints(&self) -> Constraints {
4194        self.viewport_hint
4195            .map(Constraints::tight)
4196            .unwrap_or(Constraints::UNBOUNDED)
4197    }
4198
4199    fn dpi_info_for_viewport(&self, viewport: Size) -> DpiInfo {
4200        DpiInfo::new(
4201            self.scale_factor,
4202            self.raw_dpi,
4203            viewport,
4204            scale_viewport_to_surface_size(viewport, self.scale_factor),
4205        )
4206        .with_safe_area(self.safe_area)
4207    }
4208
4209    fn current_dpi_info(&self) -> DpiInfo {
4210        let viewport = self.viewport.or(self.viewport_hint).unwrap_or(Size::ZERO);
4211        self.dpi_info_for_viewport(viewport)
4212    }
4213
4214    fn clear_inspector_history(&mut self) {
4215        self.event_route_history.clear();
4216        self.reactive_invalidation_history.clear();
4217        self.command_dispatch_history.clear();
4218        self.invalidation_history.clear();
4219        self.widget_rebuild_history.clear();
4220    }
4221
4222    fn capture_inspector_diagnostics(&mut self, diagnostics: &RenderDiagnostics) {
4223        if !self.inspector_tracing_enabled {
4224            return;
4225        }
4226
4227        extend_inspector_history(
4228            &mut self.reactive_invalidation_history,
4229            diagnostics.reactive_invalidations.iter().cloned(),
4230        );
4231        extend_inspector_history(
4232            &mut self.command_dispatch_history,
4233            diagnostics.command_dispatches.iter().cloned(),
4234        );
4235        extend_inspector_history(
4236            &mut self.invalidation_history,
4237            diagnostics.invalidations.iter().cloned(),
4238        );
4239        extend_inspector_history(
4240            &mut self.widget_rebuild_history,
4241            diagnostics.widget_rebuilds.iter().cloned(),
4242        );
4243        self.last_render_diagnostics = diagnostics.clone();
4244    }
4245
4246    fn scheduler_snapshot(&self) -> SchedulerInspectorSnapshot {
4247        let mut timers = self
4248            .scheduled_timers
4249            .iter()
4250            .map(|timer| TimerInspectorSnapshot {
4251                token: timer.token,
4252                target: timer.target,
4253                deadline: timer.deadline,
4254                delivering: self.delivering_timers.contains_key(&timer.token),
4255            })
4256            .collect::<Vec<_>>();
4257        for (&token, &target) in &self.delivering_timers {
4258            if timers.iter().all(|timer| timer.token != token) {
4259                timers.push(TimerInspectorSnapshot {
4260                    token,
4261                    target,
4262                    deadline: self.last_tick_time,
4263                    delivering: true,
4264                });
4265            }
4266        }
4267        timers.sort_by(|left, right| left.deadline.total_cmp(&right.deadline));
4268
4269        let mut async_tasks = self
4270            .async_wake_targets
4271            .iter()
4272            .map(|(&token, &target)| AsyncTaskInspectorSnapshot {
4273                token,
4274                target,
4275                pending_wake: self.pending_async_wakeups.contains(&token),
4276            })
4277            .collect::<Vec<_>>();
4278        async_tasks.sort_by_key(|task| task.token.get());
4279
4280        SchedulerInspectorSnapshot {
4281            timers,
4282            async_tasks,
4283            requested_animation_frames: self.requested_animation_frames.iter().copied().collect(),
4284            delivering_animation_frames: self.delivering_animation_frames.iter().copied().collect(),
4285            last_animation_frame_time: self.last_animation_frame_time,
4286        }
4287    }
4288
4289    fn inspector_snapshot(&self) -> WindowInspectorSnapshot {
4290        let mut widget_diagnostics = Vec::new();
4291        self.root.collect_diagnostics(&mut widget_diagnostics);
4292        WindowInspectorSnapshot {
4293            window_id: self.id,
4294            title: self.title.clone(),
4295            tracing_enabled: self.inspector_tracing_enabled,
4296            focus_state: self.focus,
4297            schedule: self.schedule,
4298            semantics: self.last_semantics.clone(),
4299            widget_graph: self.graph.snapshot(),
4300            overlays: self.overlay_manager.snapshot(),
4301            scheduler: self.scheduler_snapshot(),
4302            widget_diagnostics,
4303            last_render_diagnostics: self.last_render_diagnostics.clone(),
4304            history: InspectorHistorySnapshot {
4305                event_routes: self.event_route_history.iter().cloned().collect(),
4306                reactive_invalidations: self
4307                    .reactive_invalidation_history
4308                    .iter()
4309                    .cloned()
4310                    .collect(),
4311                command_dispatches: self.command_dispatch_history.iter().cloned().collect(),
4312                invalidations: self.invalidation_history.iter().cloned().collect(),
4313                widget_rebuilds: self.widget_rebuild_history.iter().cloned().collect(),
4314            },
4315            scene: self.last_frame.as_ref().map(|frame| {
4316                SceneStatistics::from_frame_with_mode(
4317                    frame,
4318                    self.graph.nodes.len(),
4319                    window_scene_statistics_detail_mode(self.id),
4320                )
4321            }),
4322        }
4323    }
4324}
4325
4326impl Drop for WindowState {
4327    fn drop(&mut self) {
4328        reactive::unregister_window(self.id);
4329        diagnostics::clear_widget_rebuilds(self.id);
4330    }
4331}
4332
4333fn normalize_scale_factor(scale_factor: f32) -> f32 {
4334    if scale_factor.is_finite() && scale_factor > 0.0 {
4335        scale_factor
4336    } else {
4337        1.0
4338    }
4339}
4340
4341fn scale_viewport_to_surface_size(viewport: Size, scale_factor: f32) -> Size {
4342    if viewport.is_empty() {
4343        return Size::ZERO;
4344    }
4345
4346    let scale_factor = normalize_scale_factor(scale_factor);
4347    Size::new(
4348        (viewport.width * scale_factor).round().max(1.0),
4349        (viewport.height * scale_factor).round().max(1.0),
4350    )
4351}
4352
4353impl WindowState {
4354    fn assemble_semantics_tree(&mut self, nodes: Vec<SemanticsNode>) -> Vec<SemanticsNode> {
4355        let semantic_ids: HashSet<_> = nodes.iter().map(|node| node.id).collect();
4356        if self
4357            .focused_semantics
4358            .is_some_and(|focused| !semantic_ids.contains(&focused))
4359        {
4360            self.focused_semantics = self.focus.focused_widget;
4361        }
4362
4363        nodes
4364            .into_iter()
4365            .map(|mut node| {
4366                node.parent = self.resolve_semantics_parent(&semantic_ids, node.id, node.parent);
4367                node.state.focused |= Some(node.id) == self.focused_semantics;
4368                node
4369            })
4370            .collect()
4371    }
4372
4373    fn resolve_semantics_parent(
4374        &self,
4375        semantic_ids: &HashSet<WidgetId>,
4376        widget_id: WidgetId,
4377        explicit_parent: Option<WidgetId>,
4378    ) -> Option<WidgetId> {
4379        if let Some(parent) =
4380            explicit_parent.filter(|parent| *parent != widget_id && semantic_ids.contains(parent))
4381        {
4382            return Some(parent);
4383        }
4384
4385        let mut current = self.graph.node(widget_id).and_then(|node| node.parent);
4386        while let Some(candidate) = current {
4387            if semantic_ids.contains(&candidate) {
4388                return Some(candidate);
4389            }
4390            current = self.graph.node(candidate).and_then(|node| node.parent);
4391        }
4392        None
4393    }
4394}
4395
4396#[derive(Default)]
4397struct WidgetGraph {
4398    root: WidgetId,
4399    nodes: HashMap<WidgetId, WidgetNodeSnapshot>,
4400    order: Vec<WidgetId>,
4401    host_surface_order: HashMap<WidgetId, Vec<WidgetId>>,
4402    host_order_policy: HashMap<WidgetId, StackOrderPolicy>,
4403    overlay_options: HashMap<WidgetId, OverlayOptions>,
4404    overlay_parents: HashMap<WidgetId, Option<WidgetId>>,
4405    overlay_surfaces: HashMap<WidgetId, Vec<WidgetId>>,
4406}
4407
4408#[derive(Clone, Copy)]
4409struct GraphCollectContext {
4410    stack_host: WidgetId,
4411    stack_surface: WidgetId,
4412    overlay_owner: Option<WidgetId>,
4413}
4414
4415impl WidgetGraph {
4416    fn empty(root: WidgetId) -> Self {
4417        Self {
4418            root,
4419            nodes: HashMap::new(),
4420            order: Vec::new(),
4421            host_surface_order: HashMap::new(),
4422            host_order_policy: HashMap::new(),
4423            overlay_options: HashMap::new(),
4424            overlay_parents: HashMap::new(),
4425            overlay_surfaces: HashMap::new(),
4426        }
4427    }
4428
4429    fn rebuild(
4430        root: &WidgetPod,
4431        focused_widget: Option<WidgetId>,
4432        paint_bounds_by_widget: &HashMap<WidgetId, Rect>,
4433    ) -> Self {
4434        let mut graph = Self::empty(root.id());
4435        graph.collect(
4436            root,
4437            None,
4438            focused_widget,
4439            paint_bounds_by_widget,
4440            GraphCollectContext {
4441                stack_host: root.id(),
4442                stack_surface: root.id(),
4443                overlay_owner: None,
4444            },
4445        );
4446        graph.recompute_stack_surface_order();
4447        graph
4448    }
4449
4450    fn recompute_stack_surface_order(&mut self) {
4451        let mut position_by_surface = HashMap::<(WidgetId, WidgetId), usize>::new();
4452        for (host, surfaces) in &self.host_surface_order {
4453            for (index, surface) in surfaces.iter().copied().enumerate() {
4454                position_by_surface.insert((*host, surface), index);
4455            }
4456        }
4457
4458        for node in self.nodes.values_mut() {
4459            if let Some(order) = position_by_surface.get(&(node.stack_host, node.stack_surface)) {
4460                node.stack_surface_order = *order;
4461            }
4462        }
4463    }
4464
4465    fn update_paint_bounds_from_snapshot(
4466        &mut self,
4467        paint_bounds_by_widget: &HashMap<WidgetId, Rect>,
4468    ) {
4469        for node in self.nodes.values_mut() {
4470            node.geometry.paint_bounds = paint_bounds_by_widget
4471                .get(&node.id)
4472                .copied()
4473                .unwrap_or(node.geometry.layout_bounds);
4474        }
4475    }
4476
4477    fn set_focused_widget(&mut self, focused_widget: Option<WidgetId>) {
4478        for node in self.nodes.values_mut() {
4479            node.focused = Some(node.id) == focused_widget;
4480        }
4481    }
4482
4483    fn is_empty(&self) -> bool {
4484        self.nodes.is_empty()
4485    }
4486
4487    fn contains(&self, widget_id: WidgetId) -> bool {
4488        self.nodes.contains_key(&widget_id)
4489    }
4490
4491    fn node(&self, widget_id: WidgetId) -> Option<&WidgetNodeSnapshot> {
4492        self.nodes.get(&widget_id)
4493    }
4494
4495    fn snapshot(&self) -> WidgetGraphSnapshot {
4496        let mut stack_hosts = self
4497            .host_order_policy
4498            .iter()
4499            .map(|(host, order_policy)| StackHostSnapshot {
4500                host: *host,
4501                order_policy: *order_policy,
4502                surfaces: self
4503                    .host_surface_order
4504                    .get(host)
4505                    .cloned()
4506                    .unwrap_or_default(),
4507            })
4508            .collect::<Vec<_>>();
4509        stack_hosts.sort_by_key(|host| host.host.get());
4510
4511        WidgetGraphSnapshot {
4512            root: self.root,
4513            nodes: self
4514                .order
4515                .iter()
4516                .filter_map(|widget_id| self.nodes.get(widget_id).cloned())
4517                .collect(),
4518            stack_hosts,
4519        }
4520    }
4521
4522    fn hit_test(&self, point: Point) -> Option<WidgetId> {
4523        self.hit_test_node(self.root, point)
4524    }
4525
4526    fn hit_test_within(&self, widget_id: WidgetId, point: Point) -> Option<WidgetId> {
4527        self.hit_test_node(widget_id, point)
4528    }
4529
4530    fn path_to(&self, target: WidgetId) -> Option<Vec<WidgetId>> {
4531        let mut path = Vec::new();
4532        let mut current = Some(target);
4533
4534        while let Some(widget_id) = current {
4535            let node = self.node(widget_id)?;
4536            path.push(widget_id);
4537            current = node.parent;
4538        }
4539
4540        path.reverse();
4541        Some(path)
4542    }
4543
4544    fn depth(&self, target: WidgetId) -> Option<usize> {
4545        let mut depth = 0usize;
4546        let mut current = Some(target);
4547        while let Some(widget_id) = current {
4548            let node = self.node(widget_id)?;
4549            depth += 1;
4550            current = node.parent;
4551        }
4552        Some(depth)
4553    }
4554
4555    fn is_ancestor_of(&self, ancestor: WidgetId, target: WidgetId) -> bool {
4556        let mut current = self.node(target).and_then(|node| node.parent);
4557        while let Some(widget_id) = current {
4558            if widget_id == ancestor {
4559                return true;
4560            }
4561            current = self.node(widget_id).and_then(|node| node.parent);
4562        }
4563        false
4564    }
4565
4566    fn extend_ancestors(&self, target: WidgetId, ancestors: &mut HashSet<WidgetId>) -> bool {
4567        let mut current = Some(target);
4568        while let Some(widget_id) = current {
4569            let Some(node) = self.node(widget_id) else {
4570                return false;
4571            };
4572            ancestors.insert(widget_id);
4573            current = node.parent;
4574        }
4575        true
4576    }
4577
4578    fn subtree_ids(&self, root: WidgetId) -> Vec<WidgetId> {
4579        let mut subtree = Vec::new();
4580        let mut pending = vec![root];
4581        while let Some(widget_id) = pending.pop() {
4582            let Some(node) = self.node(widget_id) else {
4583                continue;
4584            };
4585            subtree.push(widget_id);
4586            pending.extend(node.children.iter().copied());
4587        }
4588        subtree
4589    }
4590
4591    fn nearest_paint_boundary_ancestor_or_root(&self, widget_id: WidgetId) -> WidgetId {
4592        let mut current = Some(widget_id);
4593        while let Some(candidate) = current {
4594            let Some(node) = self.node(candidate) else {
4595                break;
4596            };
4597            if node.paint_boundary == PaintBoundaryMode::Explicit {
4598                return candidate;
4599            }
4600            current = node.parent;
4601        }
4602        self.root
4603    }
4604
4605    fn next_focusable(&self, current: Option<WidgetId>, backwards: bool) -> Option<WidgetId> {
4606        let focusable: Vec<_> = self
4607            .order
4608            .iter()
4609            .copied()
4610            .filter(|widget_id| self.node(*widget_id).is_some_and(|node| node.accepts_focus))
4611            .collect();
4612
4613        if focusable.is_empty() {
4614            return None;
4615        }
4616
4617        let fallback = if backwards {
4618            focusable.last().copied()
4619        } else {
4620            focusable.first().copied()
4621        };
4622
4623        let Some(current) = current else {
4624            return fallback;
4625        };
4626
4627        let Some(index) = focusable.iter().position(|widget_id| *widget_id == current) else {
4628            return fallback;
4629        };
4630
4631        if backwards {
4632            Some(focusable[(index + focusable.len() - 1) % focusable.len()])
4633        } else {
4634            Some(focusable[(index + 1) % focusable.len()])
4635        }
4636    }
4637
4638    fn first_focusable_within(
4639        &self,
4640        overlay_owner: WidgetId,
4641        include_owner: bool,
4642    ) -> Option<WidgetId> {
4643        self.order.iter().copied().find(|candidate| {
4644            self.node(*candidate).is_some_and(|node| node.accepts_focus)
4645                && (include_owner && *candidate == overlay_owner
4646                    || self.is_ancestor_of(overlay_owner, *candidate))
4647        })
4648    }
4649
4650    fn next_focusable_within(
4651        &self,
4652        scope: WidgetId,
4653        current: Option<WidgetId>,
4654        backwards: bool,
4655    ) -> Option<WidgetId> {
4656        let focusable = self
4657            .order
4658            .iter()
4659            .copied()
4660            .filter(|candidate| {
4661                self.node(*candidate).is_some_and(|node| node.accepts_focus)
4662                    && (*candidate == scope || self.is_ancestor_of(scope, *candidate))
4663            })
4664            .collect::<Vec<_>>();
4665        if focusable.is_empty() {
4666            return None;
4667        }
4668        let fallback = if backwards {
4669            focusable.last().copied()
4670        } else {
4671            focusable.first().copied()
4672        };
4673        let Some(current) = current else {
4674            return fallback;
4675        };
4676        let Some(index) = focusable.iter().position(|candidate| *candidate == current) else {
4677            return fallback;
4678        };
4679        if backwards {
4680            Some(focusable[(index + focusable.len() - 1) % focusable.len()])
4681        } else {
4682            Some(focusable[(index + 1) % focusable.len()])
4683        }
4684    }
4685
4686    fn overlay_snapshots(&self) -> Vec<OverlaySnapshot> {
4687        self.order
4688            .iter()
4689            .copied()
4690            .filter_map(|owner| {
4691                let options = self.overlay_options.get(&owner).copied()?;
4692                Some(OverlaySnapshot {
4693                    owner,
4694                    parent: self.overlay_parents.get(&owner).copied().flatten(),
4695                    surfaces: self
4696                        .overlay_surfaces
4697                        .get(&owner)
4698                        .cloned()
4699                        .unwrap_or_default(),
4700                    options,
4701                    order: 0,
4702                })
4703            })
4704            .enumerate()
4705            .map(|(order, mut snapshot)| {
4706                snapshot.order = order;
4707                snapshot
4708            })
4709            .collect()
4710    }
4711
4712    fn collect(
4713        &mut self,
4714        pod: &WidgetPod,
4715        parent: Option<WidgetId>,
4716        focused_widget: Option<WidgetId>,
4717        paint_bounds_by_widget: &HashMap<WidgetId, Rect>,
4718        context: GraphCollectContext,
4719    ) {
4720        let id = pod.id();
4721        self.order.push(id);
4722
4723        let overlay_options = pod.current_overlay_options();
4724        let is_overlay_owner = overlay_options.is_some();
4725        let overlay_owner = if is_overlay_owner {
4726            Some(id)
4727        } else {
4728            context.overlay_owner
4729        };
4730        if let Some(options) = overlay_options {
4731            self.overlay_options.insert(id, options);
4732            self.overlay_parents.insert(id, context.overlay_owner);
4733        }
4734
4735        let host_options = if id == self.root {
4736            Some(pod.current_stack_host_options().unwrap_or_default())
4737        } else {
4738            pod.current_stack_host_options()
4739        };
4740        let is_stack_host = host_options.is_some();
4741        let resolved_host = if is_stack_host {
4742            id
4743        } else {
4744            context.stack_host
4745        };
4746        let host_policy = host_options
4747            .map(|options| options.order_policy)
4748            .unwrap_or(StackOrderPolicy::Stable);
4749        if is_stack_host {
4750            self.host_order_policy.insert(resolved_host, host_policy);
4751        } else {
4752            self.host_order_policy
4753                .entry(resolved_host)
4754                .or_insert(StackOrderPolicy::Stable);
4755        }
4756        let resolved_policy = *self
4757            .host_order_policy
4758            .get(&resolved_host)
4759            .unwrap_or(&StackOrderPolicy::Stable);
4760
4761        let surface_options = pod.current_stack_surface_options();
4762        let emits_layer = pod.current_layer_options().emits_layer();
4763        let is_direct_child_of_host = parent == Some(resolved_host);
4764        let is_stack_surface = id != self.root
4765            && emits_layer
4766            && (surface_options.is_some() || is_direct_child_of_host);
4767        let hit_test = surface_options.is_none_or(|options| options.hit_test);
4768        let resolved_surface = if is_stack_surface {
4769            id
4770        } else {
4771            context.stack_surface
4772        };
4773        let transient_owner_surface = surface_options
4774            .filter(|options| emits_layer && options.transient && context.stack_surface != id)
4775            .map(|_| context.stack_surface);
4776        if is_stack_surface {
4777            let surfaces = self.host_surface_order.entry(resolved_host).or_default();
4778            if !surfaces.contains(&id) {
4779                surfaces.push(id);
4780            }
4781        }
4782        if is_stack_surface && let Some(owner) = overlay_owner {
4783            self.overlay_surfaces.entry(owner).or_default().push(id);
4784        }
4785        let stack_surface_order = self
4786            .host_surface_order
4787            .get(&resolved_host)
4788            .and_then(|surfaces| {
4789                surfaces
4790                    .iter()
4791                    .position(|surface| *surface == resolved_surface)
4792            })
4793            .unwrap_or(0);
4794
4795        let children = {
4796            let mut visitor = CollectChildrenVisitor {
4797                graph: self,
4798                parent: id,
4799                focused_widget,
4800                paint_bounds_by_widget,
4801                context: GraphCollectContext {
4802                    stack_host: resolved_host,
4803                    stack_surface: resolved_surface,
4804                    overlay_owner,
4805                },
4806                children: Vec::new(),
4807            };
4808            pod.visit_children(&mut visitor);
4809            visitor.children
4810        };
4811
4812        let layout_bounds = pod.bounds();
4813        let input_bounds = layout_bounds;
4814        let paint_bounds = paint_bounds_by_widget
4815            .get(&id)
4816            .copied()
4817            .unwrap_or(layout_bounds);
4818
4819        self.nodes.insert(
4820            id,
4821            WidgetNodeSnapshot {
4822                id,
4823                widget_name: pod.debug_name(),
4824                parent,
4825                children,
4826                measured_size: pod.measured_size(),
4827                geometry: WidgetGeometrySnapshot::new(layout_bounds, input_bounds, paint_bounds),
4828                bounds: layout_bounds,
4829                paint_boundary: pod.current_paint_boundary_mode(),
4830                stack_host: resolved_host,
4831                stack_surface: resolved_surface,
4832                stack_surface_order,
4833                transient_owner_surface,
4834                overlay_owner,
4835                is_overlay_owner,
4836                is_stack_host,
4837                is_stack_surface,
4838                hit_test,
4839                stack_order_policy: resolved_policy,
4840                accepts_focus: pod.accepts_focus(),
4841                focused: Some(id) == focused_widget,
4842            },
4843        );
4844    }
4845
4846    fn hit_test_node(&self, widget_id: WidgetId, point: Point) -> Option<WidgetId> {
4847        let node = self.node(widget_id)?;
4848        if !node.hit_test || !node.geometry.input_bounds.contains(point) {
4849            return None;
4850        }
4851
4852        if node.is_stack_host {
4853            let mut tested_surfaces = HashSet::new();
4854            if let Some(ordered_surfaces) = self.host_surface_order.get(&node.id) {
4855                for surface_id in ordered_surfaces.iter().rev().copied() {
4856                    if surface_id == widget_id {
4857                        continue;
4858                    }
4859                    tested_surfaces.insert(surface_id);
4860                    if let Some(hit) = self.hit_test_node(surface_id, point) {
4861                        return Some(hit);
4862                    }
4863                }
4864            }
4865
4866            for child_id in node.children.iter().rev() {
4867                if self.node(*child_id).is_some_and(|child| {
4868                    child.is_stack_surface || tested_surfaces.contains(child_id)
4869                }) {
4870                    continue;
4871                }
4872                if let Some(hit) = self.hit_test_node(*child_id, point) {
4873                    return Some(hit);
4874                }
4875            }
4876
4877            return Some(widget_id);
4878        }
4879
4880        for child_id in node.children.iter().rev() {
4881            if let Some(hit) = self.hit_test_node(*child_id, point) {
4882                return Some(hit);
4883            }
4884        }
4885
4886        Some(widget_id)
4887    }
4888}
4889
4890struct CollectChildrenVisitor<'a> {
4891    graph: &'a mut WidgetGraph,
4892    parent: WidgetId,
4893    focused_widget: Option<WidgetId>,
4894    paint_bounds_by_widget: &'a HashMap<WidgetId, Rect>,
4895    context: GraphCollectContext,
4896    children: Vec<WidgetId>,
4897}
4898
4899impl WidgetPodVisitor for CollectChildrenVisitor<'_> {
4900    fn visit(&mut self, child: &WidgetPod) {
4901        self.children.push(child.id());
4902        self.graph.collect(
4903            child,
4904            Some(self.parent),
4905            self.focused_widget,
4906            self.paint_bounds_by_widget,
4907            self.context,
4908        );
4909    }
4910}
4911
4912struct EventRouteResult {
4913    path: Vec<WidgetId>,
4914    effects: EventEffects,
4915    focus_request: Option<FocusRequest>,
4916    handled: bool,
4917}
4918
4919#[derive(Default)]
4920struct HoverTransitionResult {
4921    effects: EventEffects,
4922    focus_request: Option<FocusRequest>,
4923    skip_primary_route: bool,
4924}
4925
4926#[derive(Default)]
4927struct EventEffects {
4928    invalidations: Vec<InvalidationRequest>,
4929    wake_requests: Vec<WakeRequest>,
4930    pointer_capture_requests: Vec<PointerCaptureRequest>,
4931    drag_requests: Vec<DragRequest>,
4932    drop_acceptances: Vec<DropAcceptanceRequest>,
4933    posted_events: Vec<widget::PostedEventRequest>,
4934    posted_commands: Vec<widget::PostedCommandRequest>,
4935}
4936
4937impl EventEffects {
4938    fn extend(&mut self, dispatch: widget::EventDispatch) {
4939        self.invalidations.extend(dispatch.invalidations);
4940        self.wake_requests.extend(dispatch.wake_requests);
4941        self.pointer_capture_requests
4942            .extend(dispatch.pointer_capture_requests);
4943        self.drag_requests.extend(dispatch.drag_requests);
4944        self.drop_acceptances.extend(dispatch.drop_acceptances);
4945        self.posted_events.extend(dispatch.posted_events);
4946        self.posted_commands.extend(dispatch.posted_commands);
4947    }
4948
4949    fn merge(&mut self, effects: EventEffects) {
4950        self.invalidations.extend(effects.invalidations);
4951        self.wake_requests.extend(effects.wake_requests);
4952        self.pointer_capture_requests
4953            .extend(effects.pointer_capture_requests);
4954        self.drag_requests.extend(effects.drag_requests);
4955        self.drop_acceptances.extend(effects.drop_acceptances);
4956        self.posted_events.extend(effects.posted_events);
4957        self.posted_commands.extend(effects.posted_commands);
4958    }
4959}
4960
4961fn empty_dispatch() -> widget::EventDispatch {
4962    widget::EventDispatch {
4963        handled: false,
4964        invalidations: Vec::new(),
4965        focus_request: None,
4966        wake_requests: Vec::new(),
4967        pointer_capture_requests: Vec::new(),
4968        drag_requests: Vec::new(),
4969        drop_acceptances: Vec::new(),
4970        posted_events: Vec::new(),
4971        posted_commands: Vec::new(),
4972    }
4973}
4974
4975const MAX_PENDING_TRACE_SAMPLES: usize = 512;
4976const MAX_INSPECTOR_HISTORY_SAMPLES: usize = 256;
4977
4978fn push_trace<T>(samples: &mut Vec<T>, sample: T) {
4979    if samples.len() == MAX_PENDING_TRACE_SAMPLES {
4980        samples.remove(0);
4981    }
4982    samples.push(sample);
4983}
4984
4985fn extend_traces<T>(samples: &mut Vec<T>, additions: impl IntoIterator<Item = T>) {
4986    for sample in additions {
4987        push_trace(samples, sample);
4988    }
4989}
4990
4991fn push_inspector_history<T>(samples: &mut VecDeque<T>, sample: T) {
4992    if samples.len() == MAX_INSPECTOR_HISTORY_SAMPLES {
4993        samples.pop_front();
4994    }
4995    samples.push_back(sample);
4996}
4997
4998fn extend_inspector_history<T>(samples: &mut VecDeque<T>, additions: impl IntoIterator<Item = T>) {
4999    for sample in additions {
5000        push_inspector_history(samples, sample);
5001    }
5002}
5003
5004fn command_sample(
5005    command: &QueuedCommand,
5006    handlers: Vec<String>,
5007    handled: bool,
5008    delivered: bool,
5009) -> CommandDispatchSample {
5010    CommandDispatchSample {
5011        sequence: command.sequence,
5012        name: command.key.name.to_string(),
5013        payload_type: command.key.payload_type_name.to_string(),
5014        target: command.target,
5015        delivery: command.delivery,
5016        handlers,
5017        handled,
5018        delivered,
5019    }
5020}
5021
5022fn event_trace_source(event: &Event) -> String {
5023    let kind = match event {
5024        Event::Pointer(event) => format!("pointer:{:?}", event.kind),
5025        Event::Drag(event) => format!("drag:{:?}", event.kind),
5026        Event::Keyboard(_) => "keyboard".to_string(),
5027        Event::Ime(_) => "ime".to_string(),
5028        Event::Semantics(_) => "semantics".to_string(),
5029        Event::Wake(event) => format!("wake:{event:?}"),
5030        Event::Window(event) => format!("window:{event:?}"),
5031        Event::Custom(event) => format!("custom:{}", event.kind),
5032    };
5033    format!("event:{kind}")
5034}
5035
5036fn inspector_event_kind(event: &Event) -> &'static str {
5037    match event {
5038        Event::Pointer(_) => "pointer",
5039        Event::Drag(_) => "drag",
5040        Event::Keyboard(_) => "keyboard",
5041        Event::Ime(_) => "ime",
5042        Event::Semantics(_) => "semantics",
5043        Event::Wake(_) => "wake",
5044        Event::Window(_) => "window",
5045        Event::Custom(_) => "custom",
5046    }
5047}
5048
5049fn nearest_drop_acceptance(
5050    acceptances: &[DropAcceptanceRequest],
5051    path: &[WidgetId],
5052) -> Option<DropAcceptanceRequest> {
5053    acceptances
5054        .iter()
5055        .filter_map(|acceptance| {
5056            path.iter()
5057                .position(|widget_id| *widget_id == acceptance.target)
5058                .map(|index| (index, *acceptance))
5059        })
5060        .max_by_key(|(index, _)| *index)
5061        .map(|(_, acceptance)| acceptance)
5062}
5063
5064fn collect_dirty_regions<F>(
5065    viewport: Size,
5066    invalidations: &[InvalidationRequest],
5067    repainted: bool,
5068    default_region_for: F,
5069) -> Vec<DirtyRegion>
5070where
5071    F: FnMut(&InvalidationRequest) -> Rect,
5072{
5073    let viewport_rect = Rect::from_origin_size(Point::ZERO, viewport);
5074    let mut default_region_for = default_region_for;
5075
5076    if invalidations.is_empty() {
5077        return if repainted {
5078            vec![DirtyRegion::new(viewport_rect, InvalidationKind::Paint)]
5079        } else {
5080            Vec::new()
5081        };
5082    }
5083    let mut dirty_regions: Vec<_> = invalidations
5084        .iter()
5085        .map(|request| {
5086            DirtyRegion::new(
5087                request
5088                    .region
5089                    .unwrap_or_else(|| default_region_for(request)),
5090                request.kind,
5091            )
5092        })
5093        .collect();
5094
5095    if repainted
5096        && dirty_regions
5097            .iter()
5098            .all(|region| region.kind != InvalidationKind::Paint)
5099    {
5100        dirty_regions.push(DirtyRegion::new(viewport_rect, InvalidationKind::Paint));
5101    }
5102
5103    dirty_regions
5104}
5105
5106fn collect_scene_layers(scene: &Scene) -> HashMap<WidgetId, SceneLayerDescriptor> {
5107    let mut layers = HashMap::new();
5108    scene.visit_layers(&mut |layer| {
5109        layers.insert(layer.widget_id(), layer.descriptor.clone());
5110    });
5111    layers
5112}
5113
5114fn retain_text_layouts_for_scene(text_system: &TextSystem, scene: &Scene) {
5115    text_system.retain_persistent_layouts(&active_text_layout_handles(scene));
5116}
5117
5118fn active_text_layout_handles(scene: &Scene) -> HashSet<TextLayoutHandle> {
5119    let mut handles = HashSet::new();
5120    scene.visit_commands(&mut |command| match command {
5121        SceneCommand::DrawShapedText(text) => {
5122            handles.insert(text.layout_handle);
5123        }
5124        SceneCommand::DrawShapedTextWindow(text) => {
5125            handles.insert(text.layout_handle);
5126        }
5127        _ => {}
5128    });
5129    handles
5130}
5131
5132fn resolve_snapshot_paint_boundary_or_root(
5133    snapshot: &WidgetGraphSnapshot,
5134    widget_id: WidgetId,
5135) -> WidgetId {
5136    let nodes = snapshot
5137        .nodes
5138        .iter()
5139        .map(|node| (node.id, node))
5140        .collect::<HashMap<_, _>>();
5141    let mut current = Some(widget_id);
5142    while let Some(candidate) = current {
5143        let Some(node) = nodes.get(&candidate) else {
5144            break;
5145        };
5146        if node.paint_boundary == PaintBoundaryMode::Explicit {
5147            return candidate;
5148        }
5149        current = node.parent;
5150    }
5151    snapshot.root
5152}
5153
5154#[derive(Debug, Clone, Copy, PartialEq, Eq)]
5155enum HitTestCompositionPhase {
5156    Normal,
5157    Overlay,
5158    Effect,
5159}
5160
5161fn scene_hit_test_for_phase(
5162    scene: &Scene,
5163    point: Point,
5164    target_phase: HitTestCompositionPhase,
5165    inherited_phase: HitTestCompositionPhase,
5166) -> Option<WidgetId> {
5167    for command in scene.commands().iter().rev() {
5168        let SceneCommand::Layer(layer) = command else {
5169            continue;
5170        };
5171
5172        let layer_phase = next_hit_test_phase(inherited_phase, layer.descriptor.composition_mode);
5173        if !layer.descriptor.paint_bounds.contains(point) {
5174            continue;
5175        }
5176        if !layer.descriptor.hit_test {
5177            continue;
5178        }
5179
5180        if let Some(hit) = scene_hit_test_for_phase(&layer.scene, point, target_phase, layer_phase)
5181        {
5182            return Some(hit);
5183        }
5184
5185        if layer_phase == target_phase {
5186            return Some(layer.widget_id());
5187        }
5188    }
5189
5190    None
5191}
5192
5193fn next_hit_test_phase(
5194    inherited_phase: HitTestCompositionPhase,
5195    composition_mode: LayerCompositionMode,
5196) -> HitTestCompositionPhase {
5197    match (inherited_phase, composition_mode) {
5198        (HitTestCompositionPhase::Effect, _) | (_, LayerCompositionMode::Effect) => {
5199            HitTestCompositionPhase::Effect
5200        }
5201        (HitTestCompositionPhase::Overlay, _) | (_, LayerCompositionMode::Overlay) => {
5202            HitTestCompositionPhase::Overlay
5203        }
5204        _ => HitTestCompositionPhase::Normal,
5205    }
5206}
5207
5208fn invalidation_to_layer_update_kind(kind: InvalidationKind) -> Option<SceneLayerUpdateKind> {
5209    match kind {
5210        InvalidationKind::Measure | InvalidationKind::Arrange | InvalidationKind::Transform => {
5211            Some(SceneLayerUpdateKind::Transform)
5212        }
5213        InvalidationKind::Ordering => Some(SceneLayerUpdateKind::Ordering),
5214        InvalidationKind::Clip => Some(SceneLayerUpdateKind::Clip),
5215        InvalidationKind::Effect => Some(SceneLayerUpdateKind::Effect),
5216        InvalidationKind::Visibility => Some(SceneLayerUpdateKind::Visibility),
5217        InvalidationKind::Paint | InvalidationKind::Text => Some(SceneLayerUpdateKind::Content),
5218        InvalidationKind::Resources => Some(SceneLayerUpdateKind::Resources),
5219        InvalidationKind::HitTest | InvalidationKind::Semantics => None,
5220    }
5221}
5222
5223fn merge_layer_update_kind(
5224    updates: &mut HashMap<WidgetId, SceneLayerUpdateKind>,
5225    widget_id: WidgetId,
5226    kind: SceneLayerUpdateKind,
5227) {
5228    updates
5229        .entry(widget_id)
5230        .and_modify(|current| {
5231            if layer_update_priority(kind) > layer_update_priority(*current) {
5232                *current = kind;
5233            }
5234        })
5235        .or_insert(kind);
5236}
5237
5238fn layer_update_priority(kind: SceneLayerUpdateKind) -> u8 {
5239    match kind {
5240        SceneLayerUpdateKind::Visibility => 0,
5241        SceneLayerUpdateKind::Ordering => 1,
5242        SceneLayerUpdateKind::Transform => 2,
5243        SceneLayerUpdateKind::Clip => 3,
5244        SceneLayerUpdateKind::Content => 4,
5245        SceneLayerUpdateKind::Effect => 5,
5246        SceneLayerUpdateKind::Resources => 6,
5247    }
5248}
5249
5250#[derive(Debug, Clone, PartialEq)]
5251pub struct RenderOutput {
5252    pub title: String,
5253    pub frame: SceneFrame,
5254    pub semantics: Vec<SemanticsNode>,
5255    pub ime_composition_rect: Option<Rect>,
5256    pub diagnostics: RenderDiagnostics,
5257}
5258
5259#[cfg(test)]
5260mod tests;