Skip to main content

sim_logic/platform/
desktop.rs

1//! One-window desktop adapter for the shared Sim;Logic frame driver.
2//!
3//! Run the adapter on the process main thread. The underlying platform may
4//! permit only one event-loop creation for the lifetime of the process.
5//! Focus loss cancels held controls through the shared input core. Synthetic
6//! keyboard events and repeated presses are ignored; returning to the window
7//! requires a fresh physical press before a key becomes held again.
8
9#[path = "desktop/budget_recovery.rs"]
10mod budget_recovery;
11#[path = "desktop/capture.rs"]
12mod capture;
13#[path = "desktop/draw_plan.rs"]
14mod draw_plan;
15#[path = "desktop/geometry.rs"]
16mod geometry;
17#[path = "desktop/images.rs"]
18mod images;
19#[path = "desktop/keyboard.rs"]
20mod keyboard;
21#[path = "desktop/pointer.rs"]
22mod pointer;
23#[cfg(feature = "text")]
24#[path = "desktop/text.rs"]
25mod text;
26#[path = "desktop/three_d.rs"]
27mod three_d;
28#[path = "desktop/timing.rs"]
29mod timing;
30#[path = "desktop/window.rs"]
31mod window;
32use keyboard::map_key;
33#[cfg(test)]
34use winit::keyboard::KeyCode;
35
36pub use geometry::{DesktopScreenError, DesktopScreenMode, DesktopScreenUpdates};
37pub use images::DesktopImageError;
38pub use pointer::DesktopPointerError;
39pub use sim_engine::FrameCacheBudget;
40#[cfg(feature = "text")]
41pub use text::{DesktopTextError, DesktopTextUpdates};
42pub use three_d::{DesktopThreeDError, DesktopThreeDUpdates};
43pub use timing::{DesktopGpuTimingSample, DesktopGpuTimings};
44
45use std::{error::Error, fmt, sync::Arc, time::Instant};
46
47use sim_engine::{
48    FrameBudget, FrameComposerError, FramePassOptions, FrameReport, GpuTimingSource,
49    Mesh3dRenderReport, RenderStatus, RendererConfigurationError, RendererFrameError,
50    RendererInitError, RendererPresentMode, RendererSurfaceStatus, WgpuRenderer,
51    WgpuRendererOptions,
52};
53use winit::{
54    application::ApplicationHandler,
55    dpi::{LogicalSize, PhysicalPosition, PhysicalSize},
56    error::{EventLoopError, OsError},
57    event::{DeviceEvent, DeviceId, ElementState, MouseScrollDelta, WindowEvent},
58    event_loop::{ActiveEventLoop, EventLoop},
59    keyboard::PhysicalKey,
60    window::{Window, WindowId},
61};
62
63use crate::{
64    app::Application,
65    headless::{
66        BeginFrameRejection, FrameOutcome, FrameRequest, FrameTransition, HeadlessRunner,
67        LogicFrameReport, RunnerBuildError,
68    },
69    identity::{WorldFactoryId, WorldGeneration},
70    input::{
71        Action, ButtonState, InputEvent, PhysicalKeyCode, PointerCapture, RelativePointerMotion,
72        RelativePointerMotionError, SUPPORTED_PHYSICAL_KEY_COUNT, physical_key_index,
73    },
74    render::FrameLimits,
75    three_d::ThreeDRenderLimits,
76};
77
78use capture::DesktopCapture;
79use images::{DesktopImages, ScreenPresentationError};
80use pointer::DesktopPointerGeometry;
81use three_d::DesktopThreeD;
82
83const DEFAULT_TITLE: &str = "Sim;Logic";
84const DEFAULT_WIDTH: f64 = 1_280.0;
85const DEFAULT_HEIGHT: f64 = 720.0;
86const MAX_TITLE_BYTES: usize = 256;
87
88/// Window and presentation settings fixed before the desktop loop starts.
89#[derive(Debug, Clone, PartialEq)]
90pub struct DesktopConfig {
91    title: String,
92    logical_width: f64,
93    logical_height: f64,
94    present_mode: RendererPresentMode,
95    frame_cache: FrameCacheBudget,
96    screen_mode: DesktopScreenMode,
97    text_batching: bool,
98    gpu_timing: bool,
99    window_mode: crate::window::WindowMode,
100}
101
102impl Default for DesktopConfig {
103    fn default() -> Self {
104        Self {
105            title: DEFAULT_TITLE.to_owned(),
106            logical_width: DEFAULT_WIDTH,
107            logical_height: DEFAULT_HEIGHT,
108            present_mode: RendererPresentMode::Vsync,
109            frame_cache: FrameCacheBudget::default(),
110            screen_mode: DesktopScreenMode::default(),
111            text_batching: true,
112            gpu_timing: false,
113            window_mode: crate::window::WindowMode::Windowed,
114        }
115    }
116}
117
118impl DesktopConfig {
119    /// Groups adjacent same-atlas labels into retained glyph batches (default).
120    /// Groups contain at most 256 labels and never cross geometry or images.
121    /// Disable for the individual-run baseline. Has no effect without `text`.
122    pub fn set_text_batching(&mut self, enabled: bool) -> &mut Self {
123        self.text_batching = enabled;
124        self
125    }
126
127    /// Returns whether the native bridge groups adjacent managed labels.
128    pub const fn text_batching(&self) -> bool {
129        self.text_batching
130    }
131
132    /// Chooses compact/prepared retention or the legacy streaming baseline.
133    /// Set before starting the host. Scene admission still uses RenderLimits;
134    /// retained resources mirror current runs, with bounded old/new overlap.
135    pub fn set_screen_mode(&mut self, mode: DesktopScreenMode) -> &mut Self {
136        self.screen_mode = mode;
137        self
138    }
139
140    /// Returns the chosen screen geometry route.
141    pub const fn screen_mode(&self) -> DesktopScreenMode {
142        self.screen_mode
143    }
144
145    /// Selects startup mode, without changing monitor video modes. An unavailable
146    /// explicit monitor rejects startup. OS submission is not visual confirmation.
147    pub fn set_window_mode(&mut self, mode: crate::window::WindowMode) -> &mut Self {
148        self.window_mode = mode;
149        self
150    }
151
152    /// Returns the startup mode (windowed by default).
153    pub const fn window_mode(&self) -> crate::window::WindowMode {
154        self.window_mode
155    }
156
157    /// Creates validated settings for one logical-size window.
158    pub fn new(
159        title: impl Into<String>,
160        logical_width: f64,
161        logical_height: f64,
162    ) -> Result<Self, DesktopConfigError> {
163        let title = title.into();
164        validate_title(&title)?;
165        validate_logical_size(logical_width, logical_height)?;
166        Ok(Self {
167            title,
168            logical_width,
169            logical_height,
170            present_mode: RendererPresentMode::Vsync,
171            frame_cache: FrameCacheBudget::default(),
172            screen_mode: DesktopScreenMode::default(),
173            text_batching: true,
174            gpu_timing: false,
175            window_mode: crate::window::WindowMode::Windowed,
176        })
177    }
178
179    /// Selects synchronized or fastest-available presentation.
180    pub fn set_present_mode(&mut self, present_mode: RendererPresentMode) -> &mut Self {
181        self.present_mode = present_mode;
182        self
183    }
184
185    /// Sets Engine's idle composition-cache limits independently of active frame limits.
186    ///
187    /// Zero cache limits disable retention, not drawing. This does not bound
188    /// image/font assets, 3D scene resources, driver memory or in-flight work.
189    /// Defaults to Engine's finite cache budget, including packed uniform uploads.
190    pub fn set_frame_cache_budget(&mut self, budget: FrameCacheBudget) -> &mut Self {
191        self.frame_cache = budget;
192        self
193    }
194
195    /// Returns the separate idle composition-cache budget.
196    pub const fn frame_cache_budget(&self) -> FrameCacheBudget {
197        self.frame_cache
198    }
199
200    /// Requests bounded asynchronous GPU pass timestamps, disabled by default.
201    ///
202    /// Unsupported adapters still start and report Engine's `Unavailable` status.
203    /// Collection never waits for the GPU; query/readback resources and polling
204    /// add explicitly reported diagnostic overhead. CPU and presentation time
205    /// are not substituted for missing measurements.
206    pub fn set_gpu_timing(&mut self, enabled: bool) -> &mut Self {
207        self.gpu_timing = enabled;
208        self
209    }
210
211    /// Returns whether optional GPU diagnostics were requested, not availability.
212    pub const fn gpu_timing(&self) -> bool {
213        self.gpu_timing
214    }
215
216    /// Returns the configured title.
217    pub fn title(&self) -> &str {
218        &self.title
219    }
220
221    /// Returns the initial logical width.
222    pub const fn logical_width(&self) -> f64 {
223        self.logical_width
224    }
225
226    /// Returns the initial logical height.
227    pub const fn logical_height(&self) -> f64 {
228        self.logical_height
229    }
230
231    /// Returns the requested presentation behavior.
232    pub const fn present_mode(&self) -> RendererPresentMode {
233        self.present_mode
234    }
235}
236
237/// Invalid desktop configuration.
238#[derive(Debug, Clone, PartialEq)]
239pub enum DesktopConfigError {
240    /// The title contains no non-whitespace character.
241    EmptyTitle,
242    /// The UTF-8 title exceeds the finite adapter limit.
243    TitleTooLong {
244        /// Maximum accepted UTF-8 byte count.
245        limit: usize,
246    },
247    /// Logical dimensions must be finite and strictly positive.
248    InvalidLogicalSize {
249        /// Rejected logical width.
250        width: f64,
251        /// Rejected logical height.
252        height: f64,
253    },
254}
255
256impl fmt::Display for DesktopConfigError {
257    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
258        match self {
259            Self::EmptyTitle => formatter.write_str("desktop window title must not be empty"),
260            Self::TitleTooLong { limit } => {
261                write!(
262                    formatter,
263                    "desktop window title exceeds {limit} UTF-8 bytes"
264                )
265            }
266            Self::InvalidLogicalSize { width, height } => write!(
267                formatter,
268                "desktop logical size must be finite and positive, got {width}x{height}"
269            ),
270        }
271    }
272}
273
274impl Error for DesktopConfigError {}
275
276/// Successful reason the desktop event loop ended.
277#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
278#[non_exhaustive]
279pub enum DesktopExitReason {
280    /// The platform window was closed or destroyed.
281    #[default]
282    WindowClosed,
283    /// A committed [`crate::commands::LogicCommands::request_exit`] command
284    /// ended the loop after its logical frame.
285    ApplicationRequested,
286}
287
288/// Frame counts and final detailed reports retained after a successful exit.
289#[derive(Debug, Default)]
290pub struct DesktopRunReport {
291    logic_frames: u64,
292    drawn_frames: u64,
293    skipped_frames: u64,
294    committed_transitions: u64,
295    device_recoveries: u64,
296    budget_rejections: u64,
297    exit_reason: DesktopExitReason,
298    last_logic_frame: Option<LogicFrameReport>,
299    last_render_frame: Option<FrameReport>,
300    last_screen_updates: Option<DesktopScreenUpdates>,
301    last_screen_extraction: Option<crate::ScreenExtractionUpdates>,
302    #[cfg(feature = "text")]
303    last_text_updates: Option<DesktopTextUpdates>,
304    renderer_description: Option<String>,
305    last_three_d_frame: Option<Mesh3dRenderReport>,
306    last_three_d_updates: Option<DesktopThreeDUpdates>,
307    three_d_updates: DesktopThreeDUpdates,
308    gpu_timings: DesktopGpuTimings,
309}
310
311impl DesktopRunReport {
312    /// Last successful composition's glyph-batch preparation, separate from
313    /// source label/atlas preparation and renderer frame uploads.
314    #[cfg(feature = "text")]
315    pub const fn last_text_updates(&self) -> Option<DesktopTextUpdates> {
316        self.last_text_updates
317    }
318
319    /// Final adapter/backend/PCI/driver, target, DPI and presentation context.
320    /// Captured once on successful exit, not formatted or allocated per frame.
321    pub fn renderer_description(&self) -> Option<&str> {
322        self.renderer_description.as_deref()
323    }
324    /// Resource preparation outside the last surface-frame report. This may
325    /// include uploads even when subsequent surface acquisition skipped.
326    pub const fn last_screen_updates(&self) -> Option<DesktopScreenUpdates> {
327        self.last_screen_updates
328    }
329
330    /// CPU screen collection/reconstruction work from the last successfully
331    /// extracted logical frame, separate from native preparation/upload counters.
332    /// Rejection or exit without extraction preserves these diagnostic counters;
333    /// they are not proof that the most recent logical frame was presented.
334    pub const fn last_screen_extraction(&self) -> Option<crate::ScreenExtractionUpdates> {
335        self.last_screen_extraction
336    }
337    /// Returns explicitly recoverable budget-rejected frames, not surface skips.
338    pub const fn budget_rejections(&self) -> u64 {
339        self.budget_rejections
340    }
341    /// Returns application frames accepted by the shared headless core.
342    pub const fn logic_frames(&self) -> u64 {
343        self.logic_frames
344    }
345
346    /// Returns frames submitted and presented by Sim;Engine.
347    pub const fn drawn_frames(&self) -> u64 {
348        self.drawn_frames
349    }
350
351    /// Returns temporary surface skips reported by Sim;Engine.
352    pub const fn skipped_frames(&self) -> u64 {
353        self.skipped_frames
354    }
355
356    /// Returns successful logical World replacements.
357    pub const fn committed_transitions(&self) -> u64 {
358        self.committed_transitions
359    }
360
361    /// Returns successful explicit device-and-surface recoveries.
362    pub const fn device_recoveries(&self) -> u64 {
363        self.device_recoveries
364    }
365
366    /// Returns why the desktop loop ended successfully.
367    pub const fn exit_reason(&self) -> DesktopExitReason {
368        self.exit_reason
369    }
370
371    /// Returns the last successfully completed logical frame, if any.
372    pub const fn last_logic_frame(&self) -> Option<&LogicFrameReport> {
373        self.last_logic_frame.as_ref()
374    }
375
376    /// Returns the last Sim;Engine presentation report, including a temporary
377    /// surface skip when that was the most recent attempt.
378    pub const fn last_render_frame(&self) -> Option<FrameReport> {
379        self.last_render_frame
380    }
381
382    /// Returns the latest frame's separate successful 3D depth-prepass report.
383    ///
384    /// This GPU work is outside FrameReport's composition budget and timings.
385    /// It may have been submitted even if the later surface frame was skipped.
386    /// A frame without an enabled 3D view resets this value to None.
387    pub const fn last_three_d_frame(&self) -> Option<Mesh3dRenderReport> {
388        self.last_three_d_frame
389    }
390
391    /// Returns resource-update work from the latest successfully prepared 3D frame.
392    /// A presentation attempt without a 3D view resets this value to `None`.
393    /// Updates can have occurred even if subsequent surface presentation skipped.
394    pub const fn last_three_d_updates(&self) -> Option<DesktopThreeDUpdates> {
395        self.last_three_d_updates
396    }
397
398    /// Returns saturating totals across all successful 3D preparations in this run.
399    /// Device recovery does not reset these host totals. They exclude work from a
400    /// failed preparation and are not a measurement of opaque driver allocations.
401    pub const fn three_d_updates(&self) -> DesktopThreeDUpdates {
402        self.three_d_updates
403    }
404
405    /// Returns current-device hardware timing status, losses and bounded samples.
406    /// Samples are associated by exact submission ID and source, not arrival order.
407    /// Final collection is nonblocking, so pending work need not appear here.
408    pub const fn gpu_timings(&self) -> &DesktopGpuTimings {
409        &self.gpu_timings
410    }
411
412    fn record_application_exit(&mut self, report: LogicFrameReport) {
413        self.exit_reason = DesktopExitReason::ApplicationRequested;
414        self.last_logic_frame = Some(report);
415    }
416}
417
418/// Fatal reason the one-window desktop loop stopped.
419#[derive(Debug)]
420pub enum DesktopRunError {
421    /// The shared logical runner could not be built.
422    Runner(RunnerBuildError),
423    /// Winit could not create or drive its event loop.
424    EventLoop(EventLoopError),
425    /// Winit could not create the application window.
426    Window(OsError),
427    /// The initial fullscreen request could not be submitted; no fallback is hidden.
428    WindowMode(crate::window::WindowModeFailure),
429    /// Sim;Engine rejected display or resize configuration.
430    RendererConfiguration(RendererConfigurationError),
431    /// Surface reconfiguration failed after one logical frame had already
432    /// completed successfully.
433    RendererConfigurationAfterFrame {
434        /// Renderer resize or scale configuration failure.
435        error: RendererConfigurationError,
436        /// Canonical logical outcome that preceded reconfiguration.
437        logic_frame: Box<LogicFrameReport>,
438    },
439    /// Sim;Engine could not derive a positive finite logical viewport.
440    LogicalViewport(sim_engine::LogicalViewportError),
441    /// Delivered desktop pointer geometry could not form a valid logical sample.
442    Pointer(DesktopPointerError),
443    /// Sim;Engine could not create its renderer.
444    RendererInitialization(RendererInitError),
445    /// The bounded desktop collector received too many mapped input events.
446    InputEventLimitExceeded {
447        /// Frozen maximum mapped input events between logical frames.
448        limit: usize,
449    },
450    /// The desktop collector could not reserve bounded input storage.
451    InputBufferAllocationFailed,
452    /// The shared core rejected BeginFrame atomically.
453    BeginFrame(BeginFrameRejection),
454    /// A private desktop/core ownership invariant was violated.
455    RuntimeInvariant,
456    /// A logical frame began but ended with a typed stage or extraction
457    /// failure. The adapter attempted one clear-only diagnostic presentation
458    /// without reusing the last World snapshot.
459    LogicFrame {
460        /// Complete logical report for the failed frame.
461        report: Box<LogicFrameReport>,
462        /// Result of the separate diagnostic-only presentation attempt.
463        diagnostic_presentation: Box<Result<FrameReport, FrameComposerError>>,
464    },
465    /// Sim;Engine rejected frame composition or presentation after the
466    /// logical frame had already completed.
467    Presentation {
468        /// Renderer or frame-composer failure.
469        error: FrameComposerError,
470        /// Canonical logical outcome that preceded the presentation failure.
471        logic_frame: Box<LogicFrameReport>,
472    },
473    /// Preparing an uncached screen image failed after the logical frame
474    /// completed. Previously uploaded immutable assets can remain cached;
475    /// the adapter does not present a partially composed frame.
476    ImagePreparation {
477        /// Source-attributed image or cache preparation failure.
478        error: DesktopImageError,
479        /// Canonical logical outcome that preceded image preparation.
480        logic_frame: Box<LogicFrameReport>,
481    },
482    /// Preparing managed text failed after CPU publication. Earlier cache
483    /// updates may remain, but no partial surface frame is presented.
484    #[cfg(feature = "text")]
485    TextPreparation {
486        /// Source-attributed font atlas, glyph run, or cache failure.
487        error: DesktopTextError,
488        /// Canonical logical outcome preceding the failure.
489        logic_frame: Box<LogicFrameReport>,
490    },
491    /// Preparing or submitting the separate 3D depth prepass failed after the
492    /// logical frame completed. Retained resources can remain warmed; no
493    /// partial surface frame is presented and canonical state is not rolled back.
494    ThreeDPreparation {
495        /// Concrete bounded preparation or whole-scene renderer error.
496        error: DesktopThreeDError,
497        /// Canonical logical outcome preceding the failed 3D preparation.
498        logic_frame: Box<LogicFrameReport>,
499    },
500    /// The one permitted recovery attempt for a lost surface failed after the
501    /// logical frame had already completed.
502    Recovery {
503        /// Renderer recovery failure.
504        error: RendererInitError,
505        /// Canonical logical outcome that preceded the recovery attempt.
506        logic_frame: Box<LogicFrameReport>,
507    },
508}
509
510impl fmt::Display for DesktopRunError {
511    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
512        match self {
513            Self::Runner(error) => write!(formatter, "logical runner failed: {error}"),
514            Self::EventLoop(error) => write!(formatter, "desktop event loop failed: {error}"),
515            Self::Window(error) => write!(formatter, "desktop window failed: {error}"),
516            Self::WindowMode(error) => {
517                write!(formatter, "initial window mode unavailable: {error:?}")
518            }
519            Self::RendererConfiguration(error) => {
520                write!(formatter, "renderer configuration failed: {error}")
521            }
522            Self::RendererConfigurationAfterFrame { error, .. } => {
523                write!(
524                    formatter,
525                    "post-frame renderer configuration failed: {error}"
526                )
527            }
528            Self::LogicalViewport(error) => write!(formatter, "logical viewport failed: {error}"),
529            Self::Pointer(error) => write!(formatter, "desktop pointer conversion failed: {error}"),
530            Self::RendererInitialization(error) => {
531                write!(formatter, "renderer initialization failed: {error}")
532            }
533            Self::InputEventLimitExceeded { limit } => write!(
534                formatter,
535                "desktop input exceeded its limit of {limit} mapped events"
536            ),
537            Self::InputBufferAllocationFailed => {
538                formatter.write_str("desktop input buffer allocation failed")
539            }
540            Self::BeginFrame(error) => write!(formatter, "logical frame was rejected: {error}"),
541            Self::RuntimeInvariant => {
542                formatter.write_str("desktop adapter lost required runtime state")
543            }
544            Self::LogicFrame { report, .. } => write!(
545                formatter,
546                "logical frame {} failed after it began",
547                report.frame_index()
548            ),
549            Self::Presentation { error, .. } => {
550                write!(formatter, "frame presentation failed: {error}")
551            }
552            Self::ImagePreparation { error, .. } => {
553                write!(formatter, "desktop image preparation failed: {error}")
554            }
555            #[cfg(feature = "text")]
556            Self::TextPreparation { error, .. } => {
557                write!(formatter, "desktop text preparation failed: {error}")
558            }
559            Self::ThreeDPreparation { error, .. } => {
560                write!(formatter, "desktop 3D preparation failed: {error}")
561            }
562            Self::Recovery { error, .. } => write!(formatter, "renderer recovery failed: {error}"),
563        }
564    }
565}
566
567impl Error for DesktopRunError {
568    fn source(&self) -> Option<&(dyn Error + 'static)> {
569        match self {
570            Self::Runner(error) => Some(error),
571            Self::EventLoop(error) => Some(error),
572            Self::Window(error) => Some(error),
573            Self::WindowMode(_) => None,
574            Self::RendererConfiguration(error) => Some(error),
575            Self::RendererConfigurationAfterFrame { error, .. } => Some(error),
576            Self::LogicalViewport(error) => Some(error),
577            Self::Pointer(error) => Some(error),
578            Self::RendererInitialization(error) => Some(error),
579            Self::BeginFrame(error) => Some(error),
580            Self::Presentation { error, .. } => Some(error),
581            Self::ImagePreparation { error, .. } => Some(error),
582            #[cfg(feature = "text")]
583            Self::TextPreparation { error, .. } => Some(error),
584            Self::ThreeDPreparation { error, .. } => Some(error),
585            Self::Recovery { error, .. } => Some(error),
586            Self::InputEventLimitExceeded { .. }
587            | Self::InputBufferAllocationFailed
588            | Self::RuntimeInvariant => None,
589            Self::LogicFrame { report, .. } => report
590                .failure()
591                .map(|error| error as &(dyn Error + 'static)),
592        }
593    }
594}
595
596pub(crate) fn run<A: Action>(
597    application: Application<A>,
598    initial: WorldFactoryId,
599    config: DesktopConfig,
600) -> Result<DesktopRunReport, DesktopRunError> {
601    let input_event_limit = application.config.input_event_limit();
602    let frame_budget = frame_budget(application.config.render().frame_limits());
603    let three_d_limits = application.config.render().three_d();
604    let runner = application
605        .build_headless(initial)
606        .map_err(DesktopRunError::Runner)?;
607    let event_loop = EventLoop::new().map_err(DesktopRunError::EventLoop)?;
608    let mut desktop = DesktopHost::new(
609        runner,
610        config,
611        input_event_limit,
612        frame_budget,
613        three_d_limits,
614    );
615    event_loop
616        .run_app(&mut desktop)
617        .map_err(DesktopRunError::EventLoop)?;
618    desktop.collect_gpu_timings();
619    desktop.report.renderer_description = desktop
620        .renderer
621        .as_ref()
622        .map(|renderer| format!("{:?}", renderer.diagnostics()));
623    match desktop.fatal {
624        Some(error) => Err(error),
625        None => Ok(desktop.report),
626    }
627}
628
629struct DesktopHost<A: Action> {
630    runner: HeadlessRunner<A>,
631    config: DesktopConfig,
632    input_event_limit: usize,
633    frame_budget: FrameBudget,
634    window: Option<Arc<Window>>,
635    renderer: Option<WgpuRenderer>,
636    images: DesktopImages,
637    three_d: DesktopThreeD,
638    three_d_limits: ThreeDRenderLimits,
639    pending_events: Vec<InputEvent>,
640    input_failure: Option<InputBufferFailure>,
641    held_keys: [bool; SUPPORTED_PHYSICAL_KEY_COUNT],
642    pointer_geometry: DesktopPointerGeometry,
643    capture: DesktopCapture,
644    window_occluded: bool,
645    surface_waiting: bool,
646    last_frame: Instant,
647    report: DesktopRunReport,
648    fatal: Option<DesktopRunError>,
649}
650
651impl<A: Action> DesktopHost<A> {
652    fn new(
653        runner: HeadlessRunner<A>,
654        config: DesktopConfig,
655        input_event_limit: usize,
656        frame_budget: FrameBudget,
657        three_d_limits: ThreeDRenderLimits,
658    ) -> Self {
659        let mut images = DesktopImages::new();
660        images.screen_mode = config.screen_mode;
661        images.text_batching = config.text_batching;
662        Self {
663            runner,
664            config,
665            input_event_limit,
666            frame_budget,
667            window: None,
668            renderer: None,
669            images,
670            three_d: DesktopThreeD::new(),
671            three_d_limits,
672            pending_events: Vec::new(),
673            input_failure: None,
674            held_keys: [false; SUPPORTED_PHYSICAL_KEY_COUNT],
675            pointer_geometry: DesktopPointerGeometry::empty(),
676            capture: DesktopCapture::new(),
677            window_occluded: false,
678            surface_waiting: false,
679            last_frame: Instant::now(),
680            report: DesktopRunReport::default(),
681            fatal: None,
682        }
683    }
684
685    fn stop(&mut self, event_loop: &ActiveEventLoop, error: DesktopRunError) {
686        self.release_capture();
687        if self.fatal.is_none() {
688            self.fatal = Some(error);
689        }
690        event_loop.exit();
691    }
692
693    fn release_capture(&mut self) {
694        let status = self.capture.release();
695        self.runner.with_pointer_capture(|capture| {
696            capture.release();
697            capture.acknowledge(status);
698        });
699    }
700
701    fn synchronize_capture(&mut self) {
702        if self
703            .runner
704            .app_resource::<PointerCapture>()
705            .is_some_and(PointerCapture::pending)
706        {
707            let was_captured = self.capture.accepts_motion();
708            let backend = &mut self.capture;
709            self.runner
710                .with_pointer_capture(|capture| backend.synchronize(capture));
711            self.collect_capture_change(was_captured, self.capture.accepts_motion());
712        }
713    }
714
715    fn collect_capture_change(&mut self, was_captured: bool, captured: bool) {
716        // Captured CursorMoved events were deliberately not sent to UI. After
717        // changing ownership, the old absolute sample cannot describe the newly
718        // visible pointer. Queue the boundary before any later click and wait
719        // for fresh CursorMoved; also cancel an unfinished mouse gesture.
720        // synchronize_capture runs after the preceding frame queue was drained.
721        // Focus loss has its own single FocusLost boundary instead.
722        if was_captured != captured && self.collect_input(InputEvent::PointerLeft) {
723            self.pointer_geometry.cursor_left();
724        }
725    }
726
727    fn collect_relative_motion(&mut self, delta: (f64, f64)) -> Result<(), DesktopPointerError> {
728        if !self.capture.accepts_motion() || self.input_failure.is_some() {
729            return Ok(());
730        }
731        let motion = RelativePointerMotion::new(delta.0, delta.1)
732            .map_err(DesktopPointerError::RelativeMotion)?;
733        self.collect_input(InputEvent::relative_pointer_motion(motion));
734        Ok(())
735    }
736
737    fn collect_mouse_wheel(&mut self, delta: MouseScrollDelta) -> Result<(), DesktopPointerError> {
738        if self.input_failure.is_some() {
739            return Ok(());
740        }
741        // Do not merge wheel events: a line and a pixel have different units,
742        // and each event's pointer must stay ordered relative to clicks.
743        let event = self.pointer_geometry.mouse_wheel(delta)?;
744        self.collect_input(event);
745        Ok(())
746    }
747
748    fn collect_gpu_timings(&mut self) {
749        if let Some(renderer) = self.renderer.as_mut() {
750            self.report.gpu_timings.collect(renderer);
751        }
752    }
753
754    fn collect_key(
755        &mut self,
756        physical_key: PhysicalKey,
757        state: ElementState,
758        is_synthetic: bool,
759        repeat: bool,
760    ) {
761        // X11 can synthesize releases before Focused(false), and restore
762        // presses on focus gain. Neither is a new physical user action.
763        // Repeats must not reactivate a key cancelled by a focus boundary;
764        // returning to the window requires a fresh non-repeat press.
765        if is_synthetic || (repeat && state == ElementState::Pressed) {
766            return;
767        }
768        let Some(key) = map_key(physical_key) else {
769            return;
770        };
771        self.collect_physical_key(key, map_button_state(state));
772    }
773
774    fn collect_physical_key(&mut self, key: PhysicalKeyCode, state: ButtonState) {
775        if self.collect_input(InputEvent::key(key, state)) {
776            self.held_keys[physical_key_index(key)] = state == ButtonState::Pressed;
777        }
778    }
779
780    fn collect_input(&mut self, event: InputEvent) -> bool {
781        if self.input_failure.is_some() {
782            return false;
783        }
784        if let InputEvent::RelativePointerMotion { motion } = event
785            && let Some(InputEvent::RelativePointerMotion { motion: previous }) =
786                self.pending_events.last_mut()
787        {
788            match previous.checked_add(motion) {
789                Ok(sum) => *previous = sum,
790                Err(error) => {
791                    self.input_failure = Some(InputBufferFailure::RelativeMotion(error));
792                    return false;
793                }
794            }
795            return true;
796        }
797        // Only the trailing continuous sample is replaceable. A key, button,
798        // or leave event keeps all preceding pointer geometry causal.
799        if matches!(event, InputEvent::PointerMoved { .. })
800            && let Some(last @ InputEvent::PointerMoved { .. }) = self.pending_events.last_mut()
801        {
802            *last = event;
803            return true;
804        }
805        if self.pending_events.len() >= self.input_event_limit {
806            self.input_failure = Some(InputBufferFailure::Limit);
807            return false;
808        }
809        if self.pending_events.try_reserve(1).is_err() {
810            self.input_failure = Some(InputBufferFailure::Allocation);
811            return false;
812        }
813        self.pending_events.push(event);
814        true
815    }
816
817    fn collect_cursor(
818        &mut self,
819        position: PhysicalPosition<f64>,
820    ) -> Result<(), DesktopPointerError> {
821        if self.input_failure.is_some() || self.capture.accepts_motion() {
822            return Ok(());
823        }
824        let mut geometry = self.pointer_geometry;
825        let event = geometry.cursor_moved(position)?;
826        if self.collect_input(event) {
827            self.pointer_geometry = geometry;
828        }
829        Ok(())
830    }
831
832    fn collect_mouse_button(&mut self, button: winit::event::MouseButton, state: ElementState) {
833        if let Some(button) = pointer::map_mouse_button(button) {
834            self.collect_input(InputEvent::mouse_button(button, map_button_state(state)));
835        }
836    }
837
838    fn collect_pointer_left(&mut self) {
839        if self.capture.accepts_motion() {
840            return;
841        }
842        if self.collect_input(InputEvent::PointerLeft) {
843            self.pointer_geometry.cursor_left();
844        }
845    }
846
847    fn collect_resize(&mut self, size: PhysicalSize<u32>) -> Result<(), DesktopPointerError> {
848        if self.input_failure.is_some() {
849            return Ok(());
850        }
851        let mut geometry = self.pointer_geometry;
852        if geometry
853            .resized(size)?
854            .is_none_or(|event| self.collect_input(event))
855        {
856            self.pointer_geometry = geometry;
857        }
858        Ok(())
859    }
860
861    fn collect_scale_factor(&mut self, scale_factor: f64) -> Result<(), DesktopPointerError> {
862        if self.input_failure.is_some() {
863            return Ok(());
864        }
865        let mut geometry = self.pointer_geometry;
866        if geometry
867            .scale_factor_changed(scale_factor)?
868            .is_none_or(|event| self.collect_input(event))
869        {
870            self.pointer_geometry = geometry;
871        }
872        Ok(())
873    }
874
875    fn collect_focus_loss(&mut self) {
876        self.capture.set_focused(false);
877        self.release_capture();
878        // The shared core owns cancellation expansion and its exact ordered
879        // edge preflight. Queue one boundary, not a partially accepted batch
880        // of ordinary releases that could accidentally complete user actions.
881        if self.collect_input(InputEvent::FocusLost) {
882            self.held_keys.fill(false);
883            self.pointer_geometry.cursor_left();
884        }
885    }
886
887    fn redraw(&mut self, event_loop: &ActiveEventLoop) {
888        if !callback_may_run(self.fatal.is_some(), event_loop.exiting()) {
889            return;
890        }
891        // Service ready timestamps even when input, occlusion or an application
892        // exit prevents this redraw from submitting another frame.
893        self.collect_gpu_timings();
894        if let Some(failure) = self.input_failure {
895            let error = match failure {
896                InputBufferFailure::Limit => DesktopRunError::InputEventLimitExceeded {
897                    limit: self.input_event_limit,
898                },
899                InputBufferFailure::Allocation => DesktopRunError::InputBufferAllocationFailed,
900                InputBufferFailure::RelativeMotion(error) => {
901                    DesktopRunError::Pointer(DesktopPointerError::RelativeMotion(error))
902                }
903            };
904            self.stop(event_loop, error);
905            return;
906        }
907
908        let Some(renderer) = self.renderer.as_ref() else {
909            return;
910        };
911        let viewport = match renderer.logical_viewport() {
912            Ok(viewport) => viewport,
913            Err(error) => {
914                self.stop(event_loop, DesktopRunError::LogicalViewport(error));
915                return;
916            }
917        };
918        let now = Instant::now();
919        let elapsed = now.saturating_duration_since(self.last_frame);
920        self.last_frame = now;
921        let outcome = advance_shared_core(
922            &mut self.runner,
923            FrameRequest::new(elapsed, &self.pending_events, viewport),
924        );
925        self.pending_events.clear();
926
927        let report = match outcome {
928            FrameOutcome::Rejected(error) => {
929                self.stop(event_loop, DesktopRunError::BeginFrame(error));
930                return;
931            }
932            FrameOutcome::Advanced(report) => report,
933        };
934        self.synchronize_capture();
935        if let Some(window) = self.window.as_deref() {
936            self.runner
937                .with_window_controls(|controls| window::synchronize(window, controls));
938        }
939        self.report.logic_frames = self.report.logic_frames.saturating_add(1);
940        if let Some(updates) = report.extracted_generation().and_then(|generation| {
941            self.runner
942                .extracted_frame()
943                .filter(|frame| frame.world_generation() == generation)
944                .map(crate::ExtractedFrame::screen_extraction_updates)
945        }) {
946            self.report.last_screen_extraction = Some(updates);
947        }
948        if matches!(report.transition(), FrameTransition::Committed { .. }) {
949            self.report.committed_transitions = self.report.committed_transitions.saturating_add(1);
950        }
951        if transition_resets_wall_clock(report.transition()) {
952            // Candidate preparation is synchronous adapter work, not elapsed
953            // simulation time for the next frame.
954            self.last_frame = Instant::now();
955        }
956        let active_generation = self.runner.world_generation();
957        if let Some(rejection) = budget_recovery::logical(&report, active_generation)
958            && self
959                .runner
960                .with_presentation_feedback(|feedback| feedback.reject(rejection))
961                .is_some()
962        {
963            self.report.budget_rejections = self.report.budget_rejections.saturating_add(1);
964            self.report.last_logic_frame = Some(report);
965            return;
966        }
967        let snapshot_generation = self
968            .runner
969            .extracted_frame()
970            .map(crate::ExtractedFrame::world_generation);
971        match presentation_decision(
972            &report,
973            snapshot_generation,
974            active_generation,
975            self.window_occluded,
976        ) {
977            PresentationDecision::DiagnosticsOnly => {
978                let diagnostic_presentation = match self.renderer.as_mut() {
979                    Some(renderer) => present_diagnostics_only(renderer, self.frame_budget),
980                    None => {
981                        self.stop(event_loop, DesktopRunError::RuntimeInvariant);
982                        return;
983                    }
984                };
985                self.stop(
986                    event_loop,
987                    DesktopRunError::LogicFrame {
988                        report: Box::new(report),
989                        diagnostic_presentation: Box::new(diagnostic_presentation),
990                    },
991                );
992                return;
993            }
994            PresentationDecision::ApplicationExit => {
995                self.release_capture();
996                self.report.record_application_exit(report);
997                event_loop.exit();
998                return;
999            }
1000            PresentationDecision::SkipStaleSnapshot | PresentationDecision::SkipOccludedWindow => {
1001                self.report.last_logic_frame = Some(report);
1002                return;
1003            }
1004            PresentationDecision::PresentWorld => {}
1005        }
1006
1007        let Some(extracted) = self.runner.extracted_frame() else {
1008            self.stop(event_loop, DesktopRunError::RuntimeInvariant);
1009            return;
1010        };
1011        let Some(renderer) = self.renderer.as_mut() else {
1012            self.stop(event_loop, DesktopRunError::RuntimeInvariant);
1013            return;
1014        };
1015        self.report.last_three_d_frame = None;
1016        self.report.last_three_d_updates = None;
1017        self.report.last_screen_updates = None;
1018        #[cfg(feature = "text")]
1019        {
1020            self.report.last_text_updates = None;
1021        }
1022        if extracted.three_d().is_none() {
1023            // A World with no active 3D view must not keep a retired World's
1024            // chunk revisions alive through renderer caches.
1025            if self.three_d.color_target().is_some() {
1026                renderer.clear_frame_cache();
1027            }
1028            self.three_d.clear();
1029        }
1030        let presentation = if let Some(snapshot) = extracted.three_d() {
1031            (|| {
1032                self.images.preflight_three_d(
1033                    extracted,
1034                    self.runner.image_assets(),
1035                    self.frame_budget,
1036                    three_d::color_target_bytes(renderer)?,
1037                )?;
1038                let three_d_report =
1039                    self.three_d
1040                        .prepare(renderer, snapshot, self.three_d_limits)?;
1041                self.report.gpu_timings.submitted(
1042                    report.frame_index(),
1043                    GpuTimingSource::Scene3d,
1044                    three_d_report.gpu_timing_id(),
1045                );
1046                self.report.last_three_d_frame = Some(three_d_report);
1047                let updates = self.three_d.updates();
1048                self.report.last_three_d_updates = Some(updates);
1049                self.report.three_d_updates.accumulate(updates);
1050                images::present(
1051                    renderer,
1052                    extracted,
1053                    self.runner.image_assets(),
1054                    &mut self.images,
1055                    self.frame_budget,
1056                    self.three_d.color_target(),
1057                )
1058            })()
1059        } else if !images::needs_managed_presentation(extracted, &self.images) {
1060            present_extracted(renderer, extracted, self.frame_budget)
1061                .map_err(ScreenPresentationError::Composition)
1062        } else {
1063            images::present(
1064                renderer,
1065                extracted,
1066                self.runner.image_assets(),
1067                &mut self.images,
1068                self.frame_budget,
1069                None,
1070            )
1071        };
1072        let presentation = match presentation {
1073            Ok(report) => Ok(report),
1074            Err(ScreenPresentationError::Composition(error)) => {
1075                if let Some(rejection) =
1076                    budget_recovery::composed(&error, report.frame_index(), active_generation)
1077                    && self
1078                        .runner
1079                        .with_presentation_feedback(|feedback| feedback.reject(rejection))
1080                        .is_some()
1081                {
1082                    self.report.budget_rejections = self.report.budget_rejections.saturating_add(1);
1083                    self.report.last_logic_frame = Some(report);
1084                    return;
1085                }
1086                Err(error)
1087            }
1088            Err(ScreenPresentationError::Images(error)) => {
1089                self.stop(
1090                    event_loop,
1091                    DesktopRunError::ImagePreparation {
1092                        error,
1093                        logic_frame: Box::new(report),
1094                    },
1095                );
1096                return;
1097            }
1098            #[cfg(feature = "text")]
1099            Err(ScreenPresentationError::Text(error)) => {
1100                self.stop(
1101                    event_loop,
1102                    DesktopRunError::TextPreparation {
1103                        error,
1104                        logic_frame: Box::new(report),
1105                    },
1106                );
1107                return;
1108            }
1109            Err(ScreenPresentationError::ThreeD(error)) => {
1110                self.stop(
1111                    event_loop,
1112                    DesktopRunError::ThreeDPreparation {
1113                        error,
1114                        logic_frame: Box::new(report),
1115                    },
1116                );
1117                return;
1118            }
1119        };
1120        match presentation {
1121            Ok(render_report) => {
1122                self.report.last_screen_updates = Some(self.images.geometry.updates);
1123                #[cfg(feature = "text")]
1124                {
1125                    self.report.last_text_updates = Some(self.images.texts.updates);
1126                }
1127                self.report.gpu_timings.submitted(
1128                    report.frame_index(),
1129                    GpuTimingSource::FrameComposer,
1130                    render_report.gpu_timing_id(),
1131                );
1132                self.report.last_render_frame = Some(render_report);
1133                match render_report.status() {
1134                    RenderStatus::Drawn => {
1135                        self.runner
1136                            .with_presentation_feedback(|feedback| feedback.presented());
1137                        self.report.drawn_frames = self.report.drawn_frames.saturating_add(1);
1138                        self.surface_waiting = false;
1139                    }
1140                    RenderStatus::Skipped(status) => {
1141                        self.report.skipped_frames = self.report.skipped_frames.saturating_add(1);
1142                        if let Err(error) = self.handle_skip(status) {
1143                            let error = match error {
1144                                SkipHandlingError::RendererConfiguration(error) => {
1145                                    DesktopRunError::RendererConfigurationAfterFrame {
1146                                        error,
1147                                        logic_frame: Box::new(report),
1148                                    }
1149                                }
1150                                SkipHandlingError::Presentation(error) => {
1151                                    DesktopRunError::Presentation {
1152                                        error,
1153                                        logic_frame: Box::new(report),
1154                                    }
1155                                }
1156                            };
1157                            self.stop(event_loop, error);
1158                            return;
1159                        }
1160                    }
1161                }
1162            }
1163            Err(error) => match renderer_failure_action(&error) {
1164                RendererFailureAction::RecoverDeviceAndSurface {
1165                    reset_wall_clock_on_success,
1166                } => {
1167                    let Some(renderer) = self.renderer.as_mut() else {
1168                        return;
1169                    };
1170                    match pollster::block_on(renderer.recover_device_and_surface()) {
1171                        Ok(()) => {
1172                            self.images.clear();
1173                            self.report.device_recoveries =
1174                                self.report.device_recoveries.saturating_add(1);
1175                            self.report.gpu_timings.reset(
1176                                self.report.device_recoveries,
1177                                renderer.gpu_timing_statistics(),
1178                            );
1179                            self.report.last_render_frame = None;
1180                            self.report.last_screen_updates = None;
1181                            #[cfg(feature = "text")]
1182                            {
1183                                self.report.last_text_updates = None;
1184                            }
1185                            self.report.last_three_d_frame = None;
1186                            self.report.last_three_d_updates = None;
1187                            if let Err(error) = self.three_d.restore(renderer) {
1188                                self.stop(
1189                                    event_loop,
1190                                    DesktopRunError::ThreeDPreparation {
1191                                        error,
1192                                        logic_frame: Box::new(report),
1193                                    },
1194                                );
1195                                return;
1196                            }
1197                            if reset_wall_clock_on_success {
1198                                self.last_frame = Instant::now();
1199                            }
1200                            self.surface_waiting = false;
1201                        }
1202                        Err(error) => {
1203                            self.stop(
1204                                event_loop,
1205                                DesktopRunError::Recovery {
1206                                    error,
1207                                    logic_frame: Box::new(report),
1208                                },
1209                            );
1210                            return;
1211                        }
1212                    }
1213                }
1214                RendererFailureAction::Fail => {
1215                    self.stop(
1216                        event_loop,
1217                        DesktopRunError::Presentation {
1218                            error,
1219                            logic_frame: Box::new(report),
1220                        },
1221                    );
1222                    return;
1223                }
1224            },
1225        }
1226        self.report.last_logic_frame = Some(report);
1227    }
1228
1229    fn handle_skip(&mut self, status: RendererSurfaceStatus) -> Result<(), SkipHandlingError> {
1230        match skipped_surface_action(status) {
1231            SkippedSurfaceAction::RetryLater => self.surface_waiting = false,
1232            SkippedSurfaceAction::WaitForWindowEvent => self.surface_waiting = true,
1233            SkippedSurfaceAction::ReconfigureThenRetry => {
1234                self.surface_waiting = false;
1235                self.resize_renderer()
1236                    .map_err(SkipHandlingError::RendererConfiguration)?;
1237            }
1238            SkippedSurfaceAction::Fail => {
1239                return Err(SkipHandlingError::Presentation(FrameComposerError::Frame(
1240                    RendererFrameError::Surface(status),
1241                )));
1242            }
1243        }
1244        Ok(())
1245    }
1246
1247    fn resize_renderer(&mut self) -> Result<(), RendererConfigurationError> {
1248        let Some(renderer) = self.renderer.as_mut() else {
1249            return Ok(());
1250        };
1251        let size = self.pointer_geometry.physical_size();
1252        renderer.resize_with_scale_factor(
1253            size.width,
1254            size.height,
1255            self.pointer_geometry.scale_factor(),
1256        )
1257    }
1258}
1259
1260impl<A: Action> ApplicationHandler for DesktopHost<A> {
1261    fn resumed(&mut self, event_loop: &ActiveEventLoop) {
1262        if !callback_may_run(self.fatal.is_some(), event_loop.exiting()) || self.window.is_some() {
1263            return;
1264        }
1265        let attributes = Window::default_attributes()
1266            .with_title(self.config.title.clone())
1267            .with_inner_size(LogicalSize::new(
1268                self.config.logical_width,
1269                self.config.logical_height,
1270            ));
1271        let window = match event_loop.create_window(attributes) {
1272            Ok(window) => Arc::new(window),
1273            Err(error) => {
1274                self.stop(event_loop, DesktopRunError::Window(error));
1275                return;
1276            }
1277        };
1278        let initial_mode = self
1279            .runner
1280            .app_resource::<crate::window::WindowControls>()
1281            .and_then(crate::window::WindowControls::pending_mode)
1282            .unwrap_or(self.config.window_mode);
1283        let initial_status = window::apply_mode(&window, initial_mode);
1284        self.runner
1285            .with_window_controls(|controls| controls.acknowledge_mode(initial_status));
1286        if let crate::window::WindowModeStatus::Unavailable(error) = initial_status {
1287            self.stop(event_loop, DesktopRunError::WindowMode(error));
1288            return;
1289        }
1290        let size = window.inner_size();
1291        let scale_factor = window.scale_factor();
1292        self.pointer_geometry = match DesktopPointerGeometry::new(size, scale_factor) {
1293            Ok(geometry) => geometry,
1294            Err(error) => {
1295                self.stop(event_loop, DesktopRunError::Pointer(error));
1296                return;
1297            }
1298        };
1299        let options = match WgpuRendererOptions::new(self.config.present_mode, scale_factor) {
1300            Ok(options) => options.with_gpu_timing(self.config.gpu_timing),
1301            Err(error) => {
1302                self.stop(event_loop, DesktopRunError::RendererConfiguration(error));
1303                return;
1304            }
1305        };
1306        let mut renderer = match pollster::block_on(WgpuRenderer::new_with_options(
1307            Arc::clone(&window),
1308            size.width.max(1),
1309            size.height.max(1),
1310            options,
1311        )) {
1312            Ok(renderer) => renderer,
1313            Err(error) => {
1314                self.stop(event_loop, DesktopRunError::RendererInitialization(error));
1315                return;
1316            }
1317        };
1318        let notify_window = Arc::clone(&window);
1319        renderer.set_frame_cache_budget(self.config.frame_cache);
1320        renderer.set_pre_present_notify(move || notify_window.pre_present_notify());
1321        self.report
1322            .gpu_timings
1323            .reset(0, renderer.gpu_timing_statistics());
1324        self.window_occluded = extent_is_occluded(size.width, size.height);
1325        self.last_frame = Instant::now();
1326        self.capture.attach(Arc::clone(&window));
1327        self.window = Some(window);
1328        self.images.clear();
1329        self.three_d.clear();
1330        self.renderer = Some(renderer);
1331    }
1332
1333    fn window_event(
1334        &mut self,
1335        event_loop: &ActiveEventLoop,
1336        window_id: WindowId,
1337        event: WindowEvent,
1338    ) {
1339        // Winit may deliver already queued input/redraw after exit(). Neither
1340        // closing nor a failure permits another logical frame or cursor grab.
1341        if !callback_may_run(self.fatal.is_some(), event_loop.exiting()) {
1342            return;
1343        }
1344        let Some(window) = self.window.as_ref() else {
1345            return;
1346        };
1347        if window.id() != window_id {
1348            return;
1349        }
1350
1351        match event {
1352            WindowEvent::CloseRequested | WindowEvent::Destroyed => {
1353                self.release_capture();
1354                event_loop.exit();
1355            }
1356            WindowEvent::KeyboardInput {
1357                event,
1358                is_synthetic,
1359                ..
1360            } => self.collect_key(event.physical_key, event.state, is_synthetic, event.repeat),
1361            WindowEvent::CursorMoved { position, .. } => {
1362                if let Err(error) = self.collect_cursor(position) {
1363                    self.stop(event_loop, DesktopRunError::Pointer(error));
1364                }
1365            }
1366            WindowEvent::MouseInput { state, button, .. } => {
1367                self.collect_mouse_button(button, state)
1368            }
1369            WindowEvent::MouseWheel { delta, .. } => {
1370                if let Err(error) = self.collect_mouse_wheel(delta) {
1371                    self.stop(event_loop, DesktopRunError::Pointer(error));
1372                }
1373            }
1374            WindowEvent::CursorLeft { .. } => self.collect_pointer_left(),
1375            WindowEvent::Focused(false) => self.collect_focus_loss(),
1376            WindowEvent::Focused(true) => {
1377                self.capture.set_focused(true);
1378                self.surface_waiting = false;
1379            }
1380            WindowEvent::Resized(size) => {
1381                if let Err(error) = self.collect_resize(size) {
1382                    self.stop(event_loop, DesktopRunError::Pointer(error));
1383                    return;
1384                }
1385                self.window_occluded = extent_is_occluded(size.width, size.height);
1386                if !self.window_occluded {
1387                    self.surface_waiting = false;
1388                }
1389                if let Err(error) = self.resize_renderer() {
1390                    self.stop(event_loop, DesktopRunError::RendererConfiguration(error));
1391                }
1392            }
1393            WindowEvent::ScaleFactorChanged { scale_factor, .. } => {
1394                if let Err(error) = self.collect_scale_factor(scale_factor) {
1395                    self.stop(event_loop, DesktopRunError::Pointer(error));
1396                    return;
1397                }
1398                if let Some(renderer) = self.renderer.as_mut()
1399                    && let Err(error) = renderer.set_scale_factor(scale_factor)
1400                {
1401                    self.stop(event_loop, DesktopRunError::RendererConfiguration(error));
1402                }
1403            }
1404            WindowEvent::Occluded(occluded) => {
1405                self.window_occluded = occluded;
1406                if !occluded {
1407                    self.surface_waiting = false;
1408                }
1409            }
1410            WindowEvent::RedrawRequested => {
1411                // An explicit host redraw is one new opportunity even after a
1412                // previous surface-level Occluded result.
1413                self.surface_waiting = false;
1414                self.redraw(event_loop);
1415            }
1416            _ => {}
1417        }
1418    }
1419
1420    fn about_to_wait(&mut self, event_loop: &ActiveEventLoop) {
1421        if callback_may_run(self.fatal.is_some(), event_loop.exiting())
1422            && !self.window_occluded
1423            && !self.surface_waiting
1424            && let Some(window) = self.window.as_ref()
1425        {
1426            window.request_redraw();
1427        }
1428    }
1429
1430    fn device_event(&mut self, event_loop: &ActiveEventLoop, _: DeviceId, event: DeviceEvent) {
1431        if !callback_may_run(self.fatal.is_some(), event_loop.exiting()) {
1432            return;
1433        }
1434        if let DeviceEvent::MouseMotion { delta } = event
1435            && let Err(error) = self.collect_relative_motion(delta)
1436        {
1437            self.stop(event_loop, DesktopRunError::Pointer(error));
1438        }
1439    }
1440
1441    fn suspended(&mut self, event_loop: &ActiveEventLoop) {
1442        if callback_may_run(self.fatal.is_some(), event_loop.exiting()) {
1443            self.collect_focus_loss();
1444        }
1445    }
1446}
1447
1448/// All host callbacks share the same terminal guard. An OS close and an
1449/// application-requested exit are terminal even when no fatal error was stored.
1450const fn callback_may_run(failed: bool, exiting: bool) -> bool {
1451    !failed && !exiting
1452}
1453
1454#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1455enum PresentationDecision {
1456    DiagnosticsOnly,
1457    ApplicationExit,
1458    SkipStaleSnapshot,
1459    SkipOccludedWindow,
1460    PresentWorld,
1461}
1462
1463#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1464enum SkippedSurfaceAction {
1465    RetryLater,
1466    WaitForWindowEvent,
1467    ReconfigureThenRetry,
1468    Fail,
1469}
1470
1471#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1472enum RendererFailureAction {
1473    RecoverDeviceAndSurface { reset_wall_clock_on_success: bool },
1474    Fail,
1475}
1476
1477enum SkipHandlingError {
1478    RendererConfiguration(RendererConfigurationError),
1479    Presentation(FrameComposerError),
1480}
1481
1482fn advance_shared_core<A: Action>(
1483    runner: &mut HeadlessRunner<A>,
1484    request: FrameRequest<'_>,
1485) -> FrameOutcome {
1486    runner.advance_frame(request)
1487}
1488
1489fn presentation_decision(
1490    report: &LogicFrameReport,
1491    snapshot: Option<WorldGeneration>,
1492    active: WorldGeneration,
1493    window_occluded: bool,
1494) -> PresentationDecision {
1495    if report.failure().is_some() {
1496        return PresentationDecision::DiagnosticsOnly;
1497    }
1498    if report.exit_requested() {
1499        return PresentationDecision::ApplicationExit;
1500    }
1501    if !snapshot_is_fresh(report.extracted_generation(), snapshot, active) {
1502        return PresentationDecision::SkipStaleSnapshot;
1503    }
1504    if window_occluded {
1505        return PresentationDecision::SkipOccludedWindow;
1506    }
1507    PresentationDecision::PresentWorld
1508}
1509
1510const fn skipped_surface_action(status: RendererSurfaceStatus) -> SkippedSurfaceAction {
1511    match status {
1512        RendererSurfaceStatus::Timeout => SkippedSurfaceAction::RetryLater,
1513        RendererSurfaceStatus::Occluded => SkippedSurfaceAction::WaitForWindowEvent,
1514        RendererSurfaceStatus::Outdated => SkippedSurfaceAction::ReconfigureThenRetry,
1515        RendererSurfaceStatus::Lost | RendererSurfaceStatus::Validation => {
1516            SkippedSurfaceAction::Fail
1517        }
1518    }
1519}
1520
1521const fn renderer_failure_action(error: &FrameComposerError) -> RendererFailureAction {
1522    if matches!(
1523        error,
1524        FrameComposerError::Frame(RendererFrameError::Surface(RendererSurfaceStatus::Lost))
1525    ) {
1526        RendererFailureAction::RecoverDeviceAndSurface {
1527            reset_wall_clock_on_success: true,
1528        }
1529    } else {
1530        RendererFailureAction::Fail
1531    }
1532}
1533
1534const fn transition_resets_wall_clock(transition: &FrameTransition) -> bool {
1535    matches!(
1536        transition,
1537        FrameTransition::Committed { .. } | FrameTransition::PreparationFailed { .. }
1538    )
1539}
1540
1541const fn extent_is_occluded(width: u32, height: u32) -> bool {
1542    width == 0 || height == 0
1543}
1544
1545#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1546enum InputBufferFailure {
1547    Limit,
1548    Allocation,
1549    RelativeMotion(RelativePointerMotionError),
1550}
1551
1552fn present_extracted(
1553    renderer: &mut WgpuRenderer,
1554    extracted: &crate::ExtractedFrame,
1555    budget: FrameBudget,
1556) -> Result<FrameReport, FrameComposerError> {
1557    let mut frame = renderer.begin_frame(extracted.background(), budget)?;
1558    frame.draw_scene(
1559        extracted.world_scene(),
1560        extracted.camera(),
1561        FramePassOptions::new(0),
1562    )?;
1563    if let Some(options) = screen_pass_options(extracted.screen_scene().command_count()) {
1564        frame.draw_screen_scene(extracted.screen_scene(), options)?;
1565    }
1566    frame.present()
1567}
1568
1569fn screen_pass_options(command_count: usize) -> Option<FramePassOptions> {
1570    (command_count != 0).then(|| FramePassOptions::new(1))
1571}
1572
1573fn present_diagnostics_only(
1574    renderer: &mut WgpuRenderer,
1575    budget: FrameBudget,
1576) -> Result<FrameReport, FrameComposerError> {
1577    renderer
1578        .begin_frame(sim_engine::Color::BLACK, budget)?
1579        .present()
1580}
1581
1582const fn map_button_state(state: ElementState) -> ButtonState {
1583    match state {
1584        ElementState::Pressed => ButtonState::Pressed,
1585        ElementState::Released => ButtonState::Released,
1586    }
1587}
1588
1589fn snapshot_is_fresh(
1590    report: Option<crate::identity::WorldGeneration>,
1591    snapshot: Option<crate::identity::WorldGeneration>,
1592    active: crate::identity::WorldGeneration,
1593) -> bool {
1594    matches!((report, snapshot), (Some(report), Some(snapshot)) if report == active && snapshot == active)
1595}
1596
1597const fn frame_budget(limits: FrameLimits) -> FrameBudget {
1598    FrameBudget::new(
1599        limits.max_passes(),
1600        limits.max_commands(),
1601        limits.max_vertices(),
1602        limits.max_upload_bytes(),
1603        limits.max_texture_bytes(),
1604        limits.max_draw_calls(),
1605    )
1606}
1607
1608fn validate_title(title: &str) -> Result<(), DesktopConfigError> {
1609    if title.trim().is_empty() {
1610        return Err(DesktopConfigError::EmptyTitle);
1611    }
1612    if title.len() > MAX_TITLE_BYTES {
1613        return Err(DesktopConfigError::TitleTooLong {
1614            limit: MAX_TITLE_BYTES,
1615        });
1616    }
1617    Ok(())
1618}
1619
1620fn validate_logical_size(width: f64, height: f64) -> Result<(), DesktopConfigError> {
1621    if width.is_finite() && height.is_finite() && width > 0.0 && height > 0.0 {
1622        Ok(())
1623    } else {
1624        Err(DesktopConfigError::InvalidLogicalSize { width, height })
1625    }
1626}
1627
1628#[cfg(test)]
1629#[path = "desktop/pointer_tests.rs"]
1630mod pointer_tests;
1631
1632#[cfg(test)]
1633#[path = "desktop/input_tests.rs"]
1634mod input_tests;
1635
1636#[cfg(test)]
1637mod tests {
1638    use super::*;
1639    use std::{error::Error, time::Duration};
1640
1641    use sim_engine::{Camera2d, Color, LogicalViewport, Vec2};
1642
1643    use crate::{
1644        ExtractionError,
1645        app::{AppConfig, Application},
1646        commands::LogicCommands,
1647        headless::{CandidateFailure, FrameFailure},
1648        identity::{ApplicationId, WorldGeneration},
1649        input::{ALL_PHYSICAL_KEYS, FixedInput, InputEvent},
1650        query::Query,
1651        system::Stage,
1652        time::FixedTime,
1653        visual::{ActiveCamera2d, CircleVisual, Transform2d},
1654    };
1655
1656    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
1657    enum TestAction {
1658        MoveRight,
1659    }
1660
1661    fn move_circle(
1662        input: FixedInput<TestAction>,
1663        time: FixedTime,
1664        mut circles: Query<&mut Transform2d>,
1665    ) {
1666        if !input.held(TestAction::MoveRight) {
1667            return;
1668        }
1669        for mut transform in &mut circles {
1670            assert!(
1671                transform
1672                    .translate_by(Vec2::new(time.seconds_f32() * 60.0, 0.0))
1673                    .is_ok()
1674            );
1675        }
1676    }
1677
1678    fn spawn_second_camera(mut commands: LogicCommands) {
1679        let camera = Camera2d::new(Vec2::ZERO, 32.0);
1680        let Ok(camera) = camera else {
1681            panic!("test camera should be valid");
1682        };
1683        assert!(commands.spawn(ActiveCamera2d::new(camera)).is_ok());
1684    }
1685
1686    fn viewport(width: f32, height: f32) -> Result<LogicalViewport, Box<dyn Error>> {
1687        Ok(LogicalViewport::new(width, height)?)
1688    }
1689
1690    fn parity_runner() -> Result<HeadlessRunner<TestAction>, Box<dyn Error>> {
1691        let mut application = Application::new(AppConfig::default())?;
1692        application.bind_key(PhysicalKeyCode::KeyD, TestAction::MoveRight)?;
1693        let camera = ActiveCamera2d::new(Camera2d::new(Vec2::ZERO, 32.0)?);
1694        let circle = CircleVisual::new(1.0, Color::rgb8(68, 144, 255))?;
1695        let initial = application.register_world("desktop-parity", move |world| {
1696            world.spawn(camera)?;
1697            world.spawn((Transform2d::default(), circle))?;
1698            Ok(())
1699        })?;
1700        application.add_system(Stage::FixedUpdate, move_circle);
1701        Ok(application.build_headless(initial)?)
1702    }
1703
1704    #[test]
1705    fn desktop_configuration_rejects_unbounded_window_values() {
1706        assert!(matches!(
1707            DesktopConfig::new(" ", 800.0, 600.0),
1708            Err(DesktopConfigError::EmptyTitle)
1709        ));
1710        assert!(matches!(
1711            DesktopConfig::new("test", f64::NAN, 600.0),
1712            Err(DesktopConfigError::InvalidLogicalSize { .. })
1713        ));
1714    }
1715
1716    #[test]
1717    fn gpu_timing_is_explicitly_opt_in_without_changing_window_or_cache_settings() {
1718        let mut config = DesktopConfig::new("GPU diagnostics", 960.0, 540.0).unwrap();
1719        let before = config.clone();
1720        assert!(!DesktopConfig::default().gpu_timing());
1721        assert!(!config.gpu_timing());
1722        config.set_gpu_timing(true);
1723        assert!(config.gpu_timing());
1724        let options = WgpuRendererOptions::new(config.present_mode(), 1.25)
1725            .unwrap()
1726            .with_gpu_timing(config.gpu_timing());
1727        assert!(options.gpu_timing());
1728        config.set_gpu_timing(false);
1729        assert_eq!(config, before);
1730        let report = DesktopRunReport::default();
1731        assert!(report.gpu_timings().statistics().is_none());
1732        assert!(report.last_three_d_updates().is_none());
1733        assert_eq!(report.three_d_updates(), DesktopThreeDUpdates::default());
1734    }
1735
1736    #[test]
1737    fn screen_pass_is_optional_and_always_follows_the_world() {
1738        assert!(screen_pass_options(0).is_none());
1739        for count in [1, 256, usize::MAX] {
1740            assert_eq!(
1741                screen_pass_options(count).map(|options| options.order()),
1742                Some(1)
1743            );
1744        }
1745    }
1746
1747    #[test]
1748    fn renderer_budget_conversion_is_exact() {
1749        let source = FrameLimits::new(2, 3, 5, 7, 11, 13);
1750        let converted = frame_budget(source);
1751
1752        assert_eq!(converted.max_passes(), 2);
1753        assert_eq!(converted.max_commands(), 3);
1754        assert_eq!(converted.max_vertices(), 5);
1755        assert_eq!(converted.max_upload_bytes(), 7);
1756        assert_eq!(converted.max_texture_bytes(), 11);
1757        assert_eq!(converted.max_draw_calls(), 13);
1758    }
1759
1760    #[test]
1761    fn desktop_maps_every_supported_physical_key() {
1762        let mappings = [
1763            (KeyCode::KeyW, PhysicalKeyCode::KeyW),
1764            (KeyCode::KeyA, PhysicalKeyCode::KeyA),
1765            (KeyCode::KeyS, PhysicalKeyCode::KeyS),
1766            (KeyCode::KeyD, PhysicalKeyCode::KeyD),
1767            (KeyCode::Enter, PhysicalKeyCode::Enter),
1768            (KeyCode::Space, PhysicalKeyCode::Space),
1769            (KeyCode::ArrowLeft, PhysicalKeyCode::ArrowLeft),
1770            (KeyCode::ArrowRight, PhysicalKeyCode::ArrowRight),
1771            (KeyCode::ArrowDown, PhysicalKeyCode::ArrowDown),
1772            (KeyCode::ArrowUp, PhysicalKeyCode::ArrowUp),
1773            (KeyCode::Escape, PhysicalKeyCode::Escape),
1774            (KeyCode::KeyP, PhysicalKeyCode::KeyP),
1775            (KeyCode::KeyR, PhysicalKeyCode::KeyR),
1776            (KeyCode::KeyN, PhysicalKeyCode::KeyN),
1777            (KeyCode::Digit1, PhysicalKeyCode::Digit1),
1778            (KeyCode::Digit2, PhysicalKeyCode::Digit2),
1779            (KeyCode::Digit3, PhysicalKeyCode::Digit3),
1780            (KeyCode::Digit4, PhysicalKeyCode::Digit4),
1781            (KeyCode::Digit5, PhysicalKeyCode::Digit5),
1782            (KeyCode::F3, PhysicalKeyCode::F3),
1783            (KeyCode::F4, PhysicalKeyCode::F4),
1784            (KeyCode::F5, PhysicalKeyCode::F5),
1785            (KeyCode::F6, PhysicalKeyCode::F6),
1786            (KeyCode::F8, PhysicalKeyCode::F8),
1787            (KeyCode::F9, PhysicalKeyCode::F9),
1788            (KeyCode::KeyL, PhysicalKeyCode::KeyL),
1789            (KeyCode::KeyF, PhysicalKeyCode::KeyF),
1790            (KeyCode::KeyM, PhysicalKeyCode::KeyM),
1791            (KeyCode::KeyT, PhysicalKeyCode::KeyT),
1792            (KeyCode::KeyV, PhysicalKeyCode::KeyV),
1793            (KeyCode::Digit6, PhysicalKeyCode::Digit6),
1794            (KeyCode::Digit7, PhysicalKeyCode::Digit7),
1795            (KeyCode::Digit8, PhysicalKeyCode::Digit8),
1796            (KeyCode::Digit9, PhysicalKeyCode::Digit9),
1797            (KeyCode::F7, PhysicalKeyCode::F7),
1798            (KeyCode::KeyE, PhysicalKeyCode::KeyE),
1799            (KeyCode::ShiftLeft, PhysicalKeyCode::ShiftLeft),
1800            (KeyCode::Tab, PhysicalKeyCode::Tab),
1801            (KeyCode::Digit0, PhysicalKeyCode::Digit0),
1802            (KeyCode::F1, PhysicalKeyCode::F1),
1803            (KeyCode::F2, PhysicalKeyCode::F2),
1804            (KeyCode::F10, PhysicalKeyCode::F10),
1805            (KeyCode::F11, PhysicalKeyCode::F11),
1806            (KeyCode::F12, PhysicalKeyCode::F12),
1807            (KeyCode::ShiftRight, PhysicalKeyCode::ShiftRight),
1808            (KeyCode::ControlLeft, PhysicalKeyCode::ControlLeft),
1809            (KeyCode::ControlRight, PhysicalKeyCode::ControlRight),
1810            (KeyCode::AltLeft, PhysicalKeyCode::AltLeft),
1811            (KeyCode::AltRight, PhysicalKeyCode::AltRight),
1812            (KeyCode::SuperLeft, PhysicalKeyCode::SuperLeft),
1813            (KeyCode::SuperRight, PhysicalKeyCode::SuperRight),
1814            (KeyCode::Backspace, PhysicalKeyCode::Backspace),
1815            (KeyCode::Delete, PhysicalKeyCode::Delete),
1816            (KeyCode::Insert, PhysicalKeyCode::Insert),
1817            (KeyCode::Home, PhysicalKeyCode::Home),
1818            (KeyCode::End, PhysicalKeyCode::End),
1819            (KeyCode::PageUp, PhysicalKeyCode::PageUp),
1820            (KeyCode::PageDown, PhysicalKeyCode::PageDown),
1821            (KeyCode::CapsLock, PhysicalKeyCode::CapsLock),
1822            (KeyCode::NumLock, PhysicalKeyCode::NumLock),
1823            (KeyCode::ScrollLock, PhysicalKeyCode::ScrollLock),
1824            (KeyCode::PrintScreen, PhysicalKeyCode::PrintScreen),
1825            (KeyCode::Pause, PhysicalKeyCode::Pause),
1826            (KeyCode::ContextMenu, PhysicalKeyCode::ContextMenu),
1827            (KeyCode::Backquote, PhysicalKeyCode::Backquote),
1828            (KeyCode::Minus, PhysicalKeyCode::Minus),
1829            (KeyCode::Equal, PhysicalKeyCode::Equal),
1830            (KeyCode::BracketLeft, PhysicalKeyCode::BracketLeft),
1831            (KeyCode::BracketRight, PhysicalKeyCode::BracketRight),
1832            (KeyCode::Backslash, PhysicalKeyCode::Backslash),
1833            (KeyCode::Semicolon, PhysicalKeyCode::Semicolon),
1834            (KeyCode::Quote, PhysicalKeyCode::Quote),
1835            (KeyCode::Comma, PhysicalKeyCode::Comma),
1836            (KeyCode::Period, PhysicalKeyCode::Period),
1837            (KeyCode::Slash, PhysicalKeyCode::Slash),
1838            (KeyCode::KeyB, PhysicalKeyCode::KeyB),
1839            (KeyCode::KeyC, PhysicalKeyCode::KeyC),
1840            (KeyCode::KeyG, PhysicalKeyCode::KeyG),
1841            (KeyCode::KeyH, PhysicalKeyCode::KeyH),
1842            (KeyCode::KeyI, PhysicalKeyCode::KeyI),
1843            (KeyCode::KeyJ, PhysicalKeyCode::KeyJ),
1844            (KeyCode::KeyK, PhysicalKeyCode::KeyK),
1845            (KeyCode::KeyO, PhysicalKeyCode::KeyO),
1846            (KeyCode::KeyU, PhysicalKeyCode::KeyU),
1847            (KeyCode::KeyX, PhysicalKeyCode::KeyX),
1848            (KeyCode::KeyY, PhysicalKeyCode::KeyY),
1849            (KeyCode::KeyZ, PhysicalKeyCode::KeyZ),
1850            (KeyCode::Numpad0, PhysicalKeyCode::Numpad0),
1851            (KeyCode::Numpad1, PhysicalKeyCode::Numpad1),
1852            (KeyCode::Numpad2, PhysicalKeyCode::Numpad2),
1853            (KeyCode::Numpad3, PhysicalKeyCode::Numpad3),
1854            (KeyCode::Numpad4, PhysicalKeyCode::Numpad4),
1855            (KeyCode::Numpad5, PhysicalKeyCode::Numpad5),
1856            (KeyCode::Numpad6, PhysicalKeyCode::Numpad6),
1857            (KeyCode::Numpad7, PhysicalKeyCode::Numpad7),
1858            (KeyCode::Numpad8, PhysicalKeyCode::Numpad8),
1859            (KeyCode::Numpad9, PhysicalKeyCode::Numpad9),
1860            (KeyCode::NumpadEnter, PhysicalKeyCode::NumpadEnter),
1861            (KeyCode::NumpadAdd, PhysicalKeyCode::NumpadAdd),
1862            (KeyCode::NumpadSubtract, PhysicalKeyCode::NumpadSubtract),
1863            (KeyCode::NumpadMultiply, PhysicalKeyCode::NumpadMultiply),
1864            (KeyCode::NumpadDivide, PhysicalKeyCode::NumpadDivide),
1865            (KeyCode::NumpadDecimal, PhysicalKeyCode::NumpadDecimal),
1866            (KeyCode::NumpadEqual, PhysicalKeyCode::NumpadEqual),
1867            (KeyCode::IntlBackslash, PhysicalKeyCode::IntlBackslash),
1868            (KeyCode::IntlRo, PhysicalKeyCode::IntlRo),
1869            (KeyCode::IntlYen, PhysicalKeyCode::IntlYen),
1870            (KeyCode::KeyQ, PhysicalKeyCode::KeyQ),
1871        ];
1872
1873        assert_eq!(mappings.map(|(_, portable)| portable), ALL_PHYSICAL_KEYS);
1874        for (platform, portable) in mappings {
1875            assert_eq!(map_key(PhysicalKey::Code(platform)), Some(portable));
1876            assert_eq!(ALL_PHYSICAL_KEYS[physical_key_index(portable)], portable);
1877        }
1878        assert_eq!(map_key(PhysicalKey::Code(KeyCode::MediaPlayPause)), None);
1879        assert_eq!(
1880            map_key(PhysicalKey::Unidentified(
1881                winit::keyboard::NativeKeyCode::Unidentified
1882            )),
1883            None
1884        );
1885    }
1886
1887    #[test]
1888    fn terminal_callbacks_cannot_run_after_close_or_failure() {
1889        assert!(callback_may_run(false, false));
1890        assert!(
1891            !callback_may_run(false, true),
1892            "normal exit has no fatal error"
1893        );
1894        assert!(
1895            !callback_may_run(true, false),
1896            "failure stops before exit dispatch"
1897        );
1898        assert!(!callback_may_run(true, true));
1899    }
1900
1901    #[test]
1902    fn focus_loss_queues_one_core_owned_boundary_after_all_supported_keys()
1903    -> Result<(), Box<dyn Error>> {
1904        let mut host = DesktopHost::new(
1905            parity_runner()?,
1906            DesktopConfig::default(),
1907            ALL_PHYSICAL_KEYS.len() + 1,
1908            frame_budget(FrameLimits::default()),
1909            ThreeDRenderLimits::default(),
1910        );
1911        let new_keys = ALL_PHYSICAL_KEYS;
1912
1913        for key in new_keys.into_iter().rev() {
1914            host.collect_physical_key(key, ButtonState::Pressed);
1915        }
1916        host.collect_focus_loss();
1917
1918        assert_eq!(host.pending_events.len(), new_keys.len() + 1);
1919        for (index, key) in new_keys.into_iter().enumerate() {
1920            assert_eq!(
1921                host.pending_events[index],
1922                InputEvent::key(new_keys[new_keys.len() - index - 1], ButtonState::Pressed)
1923            );
1924            assert!(!host.held_keys[physical_key_index(key)]);
1925        }
1926        assert_eq!(host.pending_events.last(), Some(&InputEvent::FocusLost));
1927        assert_eq!(host.input_failure, None);
1928        Ok(())
1929    }
1930
1931    #[test]
1932    fn stale_or_unpublished_snapshots_are_never_fresh() {
1933        let application = ApplicationId::from_raw(9);
1934        let old = WorldGeneration::new(application, 1);
1935        let active = WorldGeneration::new(application, 2);
1936
1937        assert!(snapshot_is_fresh(Some(active), Some(active), active));
1938        assert!(!snapshot_is_fresh(Some(active), Some(old), active));
1939        assert!(!snapshot_is_fresh(Some(old), Some(active), active));
1940        assert!(!snapshot_is_fresh(None, Some(active), active));
1941        assert!(!snapshot_is_fresh(Some(active), None, active));
1942    }
1943
1944    #[test]
1945    fn desktop_adapter_and_headless_call_the_same_core_lifecycle() -> Result<(), Box<dyn Error>> {
1946        let mut desktop_core = parity_runner()?;
1947        let mut headless_core = parity_runner()?;
1948        let events = [InputEvent::key(PhysicalKeyCode::KeyD, ButtonState::Pressed)];
1949        let logical_viewport = viewport(800.0, 600.0)?;
1950
1951        let desktop_outcome = advance_shared_core(
1952            &mut desktop_core,
1953            FrameRequest::new(Duration::from_millis(25), &events, logical_viewport),
1954        );
1955        let headless_outcome = headless_core.advance_frame(FrameRequest::new(
1956            Duration::from_millis(25),
1957            &events,
1958            logical_viewport,
1959        ));
1960        let (FrameOutcome::Advanced(desktop_report), FrameOutcome::Advanced(headless_report)) =
1961            (desktop_outcome, headless_outcome)
1962        else {
1963            panic!("both bounded core frames should advance");
1964        };
1965
1966        assert_eq!(desktop_report.timing(), headless_report.timing());
1967        assert_eq!(
1968            desktop_report.fixed_ticks_attempted(),
1969            headless_report.fixed_ticks_attempted()
1970        );
1971        assert_eq!(desktop_report.spawned(), headless_report.spawned());
1972        assert_eq!(desktop_report.despawned(), headless_report.despawned());
1973        assert!(desktop_report.failure().is_none());
1974        assert!(headless_report.failure().is_none());
1975
1976        let desktop_frame = desktop_core
1977            .extracted_frame()
1978            .ok_or("desktop core should publish a frame")?;
1979        let headless_frame = headless_core
1980            .extracted_frame()
1981            .ok_or("headless core should publish a frame")?;
1982        assert_eq!(desktop_frame.background(), headless_frame.background());
1983        assert_eq!(desktop_frame.camera(), headless_frame.camera());
1984        let [desktop_circle] = desktop_frame.resolved_circles() else {
1985            panic!("desktop core should resolve one circle");
1986        };
1987        let [headless_circle] = headless_frame.resolved_circles() else {
1988            panic!("headless core should resolve one circle");
1989        };
1990        assert_eq!(desktop_circle.position(), headless_circle.position());
1991        assert_eq!(desktop_circle.radius(), headless_circle.radius());
1992        assert_eq!(desktop_circle.color(), headless_circle.color());
1993        assert_eq!(desktop_circle.layer(), headless_circle.layer());
1994        assert_eq!(
1995            desktop_circle.draw_order_depth(),
1996            headless_circle.draw_order_depth()
1997        );
1998        Ok(())
1999    }
2000
2001    #[test]
2002    fn presentation_requires_the_report_snapshot_and_active_generation_to_match()
2003    -> Result<(), Box<dyn Error>> {
2004        let mut runner = parity_runner()?;
2005        let outcome = advance_shared_core(
2006            &mut runner,
2007            FrameRequest::new(Duration::ZERO, &[], viewport(800.0, 600.0)?),
2008        );
2009        let FrameOutcome::Advanced(report) = outcome else {
2010            panic!("bounded core frame should advance");
2011        };
2012        let active = runner.world_generation();
2013        let snapshot = runner
2014            .extracted_frame()
2015            .map(crate::ExtractedFrame::world_generation);
2016        let foreign = WorldGeneration::new(ApplicationId::from_raw(900), 1);
2017
2018        assert_eq!(
2019            presentation_decision(&report, snapshot, active, false),
2020            PresentationDecision::PresentWorld
2021        );
2022        assert_eq!(
2023            presentation_decision(&report, Some(foreign), active, false),
2024            PresentationDecision::SkipStaleSnapshot
2025        );
2026        assert_eq!(
2027            presentation_decision(&report, snapshot, active, true),
2028            PresentationDecision::SkipOccludedWindow
2029        );
2030        Ok(())
2031    }
2032
2033    #[test]
2034    fn application_exit_is_recorded_without_another_presentation() -> Result<(), Box<dyn Error>> {
2035        let mut application = Application::<TestAction>::new(AppConfig::default())?;
2036        let camera = ActiveCamera2d::new(Camera2d::new(Vec2::ZERO, 32.0)?);
2037        let initial = application.register_world("desktop-exit", move |world| {
2038            world.spawn(camera)?;
2039            Ok(())
2040        })?;
2041        application.add_system(Stage::FrameUpdate, |mut commands: LogicCommands| {
2042            assert!(commands.request_exit().is_ok());
2043        });
2044        let mut runner = application.build_headless(initial)?;
2045
2046        let outcome = advance_shared_core(
2047            &mut runner,
2048            FrameRequest::new(Duration::ZERO, &[], viewport(800.0, 600.0)?),
2049        );
2050        let FrameOutcome::Advanced(report) = outcome else {
2051            panic!("bounded exit frame should advance");
2052        };
2053        assert!(report.exit_requested());
2054        assert_eq!(report.extracted_generation(), None);
2055        assert_eq!(
2056            presentation_decision(
2057                &report,
2058                runner
2059                    .extracted_frame()
2060                    .map(crate::ExtractedFrame::world_generation),
2061                runner.world_generation(),
2062                false,
2063            ),
2064            PresentationDecision::ApplicationExit
2065        );
2066
2067        let mut desktop = DesktopRunReport::default();
2068        assert_eq!(desktop.exit_reason(), DesktopExitReason::WindowClosed);
2069        desktop.record_application_exit(report);
2070        assert_eq!(
2071            desktop.exit_reason(),
2072            DesktopExitReason::ApplicationRequested
2073        );
2074        assert_eq!(desktop.drawn_frames(), 0);
2075        assert_eq!(desktop.skipped_frames(), 0);
2076        assert!(desktop.last_render_frame().is_none());
2077        assert!(
2078            desktop
2079                .last_logic_frame()
2080                .is_some_and(LogicFrameReport::exit_requested)
2081        );
2082        Ok(())
2083    }
2084
2085    #[test]
2086    fn extraction_and_renderer_failures_choose_separate_paths() -> Result<(), Box<dyn Error>> {
2087        let mut application = Application::<TestAction>::new(AppConfig::default())?;
2088        let camera = ActiveCamera2d::new(Camera2d::new(Vec2::ZERO, 32.0)?);
2089        let initial = application.register_world("invalid-after-frame", move |world| {
2090            world.spawn(camera)?;
2091            Ok(())
2092        })?;
2093        application.add_system(Stage::FrameUpdate, spawn_second_camera);
2094        let mut runner = application.build_headless(initial)?;
2095
2096        let outcome = advance_shared_core(
2097            &mut runner,
2098            FrameRequest::new(Duration::ZERO, &[], viewport(800.0, 600.0)?),
2099        );
2100        let FrameOutcome::Advanced(report) = outcome else {
2101            panic!("BeginFrame should succeed before extraction fails");
2102        };
2103        assert!(matches!(
2104            report.failure(),
2105            Some(FrameFailure::Extraction(
2106                ExtractionError::MultipleActiveCameras
2107            ))
2108        ));
2109        assert_eq!(
2110            presentation_decision(
2111                &report,
2112                runner
2113                    .extracted_frame()
2114                    .map(crate::ExtractedFrame::world_generation),
2115                runner.world_generation(),
2116                false,
2117            ),
2118            PresentationDecision::DiagnosticsOnly
2119        );
2120
2121        let renderer_validation = FrameComposerError::Frame(RendererFrameError::Surface(
2122            RendererSurfaceStatus::Validation,
2123        ));
2124        assert_eq!(
2125            renderer_failure_action(&renderer_validation),
2126            RendererFailureAction::Fail
2127        );
2128        assert_eq!(
2129            renderer_failure_action(&FrameComposerError::InvalidBackground),
2130            RendererFailureAction::Fail
2131        );
2132        Ok(())
2133    }
2134
2135    #[test]
2136    fn surface_outcomes_follow_the_desktop_retry_policy() {
2137        assert_eq!(
2138            skipped_surface_action(RendererSurfaceStatus::Timeout),
2139            SkippedSurfaceAction::RetryLater
2140        );
2141        assert_eq!(
2142            skipped_surface_action(RendererSurfaceStatus::Occluded),
2143            SkippedSurfaceAction::WaitForWindowEvent
2144        );
2145        assert_eq!(
2146            skipped_surface_action(RendererSurfaceStatus::Outdated),
2147            SkippedSurfaceAction::ReconfigureThenRetry
2148        );
2149        assert_eq!(
2150            skipped_surface_action(RendererSurfaceStatus::Lost),
2151            SkippedSurfaceAction::Fail
2152        );
2153        assert_eq!(
2154            skipped_surface_action(RendererSurfaceStatus::Validation),
2155            SkippedSurfaceAction::Fail
2156        );
2157
2158        let lost =
2159            FrameComposerError::Frame(RendererFrameError::Surface(RendererSurfaceStatus::Lost));
2160        assert_eq!(
2161            renderer_failure_action(&lost),
2162            RendererFailureAction::RecoverDeviceAndSurface {
2163                reset_wall_clock_on_success: true,
2164            }
2165        );
2166    }
2167
2168    #[test]
2169    fn resize_and_render_skip_do_not_advance_fixed_state() -> Result<(), Box<dyn Error>> {
2170        let mut runner = parity_runner()?;
2171        let pressed = [InputEvent::key(PhysicalKeyCode::KeyD, ButtonState::Pressed)];
2172        let first = advance_shared_core(
2173            &mut runner,
2174            FrameRequest::new(Duration::from_millis(17), &pressed, viewport(800.0, 600.0)?),
2175        );
2176        assert!(matches!(first, FrameOutcome::Advanced(_)));
2177        let before_resize = runner
2178            .components::<Transform2d>()
2179            .next()
2180            .map(|(_, transform)| transform.translation())
2181            .ok_or("test World should contain a transform")?;
2182
2183        assert!(!extent_is_occluded(1_200, 800));
2184        let resized = advance_shared_core(
2185            &mut runner,
2186            FrameRequest::new(Duration::ZERO, &[], viewport(1_200.0, 800.0)?),
2187        );
2188        assert!(matches!(resized, FrameOutcome::Advanced(_)));
2189        assert_eq!(
2190            skipped_surface_action(RendererSurfaceStatus::Timeout),
2191            SkippedSurfaceAction::RetryLater
2192        );
2193
2194        let after_skip = runner
2195            .components::<Transform2d>()
2196            .next()
2197            .map(|(_, transform)| transform.translation())
2198            .ok_or("test World should contain a transform")?;
2199        assert_eq!(before_resize, after_skip);
2200        assert!(extent_is_occluded(0, 800));
2201        assert!(extent_is_occluded(1_200, 0));
2202        Ok(())
2203    }
2204
2205    #[test]
2206    fn transition_and_recovery_clock_reset_policy_is_explicit() {
2207        let application = ApplicationId::from_raw(91);
2208        let old = WorldGeneration::new(application, 1);
2209        let new = WorldGeneration::new(application, 2);
2210        let target = WorldFactoryId::new(application, 0, 1);
2211
2212        assert!(!transition_resets_wall_clock(&FrameTransition::None));
2213        assert!(transition_resets_wall_clock(&FrameTransition::Committed {
2214            old,
2215            new,
2216            target,
2217            warning: None,
2218        }));
2219        assert!(transition_resets_wall_clock(
2220            &FrameTransition::PreparationFailed {
2221                target,
2222                error: CandidateFailure::InvalidFactory,
2223            }
2224        ));
2225
2226        let lost =
2227            FrameComposerError::Frame(RendererFrameError::Surface(RendererSurfaceStatus::Lost));
2228        assert_eq!(
2229            renderer_failure_action(&lost),
2230            RendererFailureAction::RecoverDeviceAndSurface {
2231                reset_wall_clock_on_success: true,
2232            }
2233        );
2234    }
2235}