ailloli_ui_winit/lib.rs
1//! `winit` integration for Ailloli UI: event loop, windows, input, GPU bootstrap, capture.
2//!
3//! This crate wires [`ailloli_ui_runtime`] to [`winit`] and [`ailloli_ui_render_wgpu`]. Application code
4//! typically uses `ailloli_ui::App`; lower-level integrations can use
5//! [`WinitHost`] around [`UiApp`], or [`run_app`] with a specialized custom
6//! [`winit::application::ApplicationHandler`].
7//!
8//! # Modules
9//!
10//! | Module | Role |
11//! |--------|------|
12//! | [`ui_app`] | Retained multi-window UI state (layout → paint → render) |
13//! | [`host`] | Sole high-level `ApplicationHandler` and provider-neutral driver bridge |
14//! | [`window`] | `WindowOptions` and window creation helpers |
15//! | [`event_loop`] / [`application`] | Event loop construction and `run_app` |
16//! | [`capture`] | WGPU readback hooks for tests and tooling |
17//! | [`resize`] | Surface resize coalescing before redraw |
18//! | [`wgpu_bootstrap`] | Create [`ailloli_ui_render_wgpu::Renderer`] from a `winit` window |
19
20/// Returns the modern environment value, falling back to a legacy name.
21///
22/// Empty and non-Unicode values are preserved. Lookup is process-global and
23/// reads `primary` first.
24///
25/// # Examples
26///
27/// ```
28/// let modern = Some(std::ffi::OsString::from("modern"));
29/// let legacy = Some(std::ffi::OsString::from("legacy"));
30/// assert_eq!(modern.or(legacy).unwrap(), "modern");
31/// ```
32pub(crate) fn framework_env_var_os(primary: &str, legacy: &str) -> Option<std::ffi::OsString> {
33 std::env::var_os(primary).or_else(|| std::env::var_os(legacy))
34}
35
36/// Returns whether either modern or legacy trace variable is present.
37///
38/// The value is not parsed: even an empty string or `0` enables tracing.
39///
40/// # Examples
41///
42/// ```
43/// let configured: Option<std::ffi::OsString> = None;
44/// assert!(!configured.is_some());
45/// ```
46pub(crate) fn winit_trace_enabled() -> bool {
47 framework_env_var_os("AILLOLI_UI_WINIT_TRACE", "OCTAVUI_WINIT_TRACE").is_some()
48}
49
50/// Shared application entry: builds an event loop and runs the handler.
51pub mod application;
52/// Frame capture for visual tests and agent tooling.
53pub mod capture;
54/// Native clipboard (`arboard`) for the runtime.
55pub mod clipboard;
56/// System cursor mapping (future `CursorStyle` bridge).
57pub mod cursor;
58#[cfg(feature = "devtools")]
59/// Optional inspector window and loopback JSONL command service.
60pub mod devtools;
61/// DPI and physical size helpers.
62pub mod dpi;
63/// Event loop helpers and Linux Ctrl+C shutdown.
64pub mod event_loop;
65/// Native browser handoff for validated external URLs.
66pub mod external_url;
67/// Provider-neutral application logic hosted by winit.
68pub mod host;
69#[cfg(feature = "native_overlay")]
70/// Native overlay surfaces and output calibration on supported platforms.
71pub mod native_overlay;
72/// OS-specific winit extensions.
73pub mod platform;
74/// Deferred GPU surface resize before redraw.
75pub mod resize;
76/// Retained multi-window UI state owned by the host adapter.
77pub mod ui_app;
78/// GPU renderer construction from a window.
79pub mod wgpu_bootstrap;
80/// Window attributes and creation.
81pub mod window;
82/// Client-side resize edges when OS decorations are off.
83pub mod window_chrome_resize;
84
85pub use application::run_app;
86
87/// Starts a reliable JSONL benchmark session when `AILLOLI_UI_BENCH=1`.
88///
89/// Uses `AILLOLI_UI_BENCH_PATH` when set; otherwise writes to `default_path`.
90/// Disabled collection returns `BenchInit::Disabled`; enabled initialization
91/// propagates typed path, writer, and global-install failures.
92///
93/// # Errors
94///
95/// When collection is enabled, returns [`ailloli_ui_bench::BenchInitError`] for
96/// invalid metadata or paths, an occupied destination/global slot, filesystem
97/// or initial-write failure, or writer-thread startup failure. Disabled
98/// collection does not fail.
99///
100/// # Examples
101///
102/// ```no_run
103/// use ailloli_ui_winit::try_init_ailloli_ui_bench_from_env;
104/// fn initialize() -> Result<(), Box<dyn std::error::Error>> {
105/// let init = try_init_ailloli_ui_bench_from_env("artifacts/bench/run.jsonl")?;
106/// let _completed = init.finish()?;
107/// Ok(())
108/// }
109/// ```
110#[inline]
111pub fn try_init_ailloli_ui_bench_from_env(
112 default_path: &str,
113) -> Result<ailloli_ui_bench::BenchInit, ailloli_ui_bench::BenchInitError> {
114 ailloli_ui_bench::try_init_from_env(default_path)
115}
116
117/// Historical append-only benchmark initialization.
118///
119/// This path cannot report finalization or dropped-record errors and is not a
120/// valid regression gate. Use [`try_init_ailloli_ui_bench_from_env`] instead.
121#[deprecated(
122 since = "0.1.0",
123 note = "use try_init_ailloli_ui_bench_from_env and retain the returned guard"
124)]
125#[allow(deprecated)]
126#[inline]
127/// # Examples
128///
129/// ```no_run
130/// #![allow(deprecated)]
131/// let path: Option<std::path::PathBuf> =
132/// ailloli_ui_winit::init_ailloli_ui_bench_from_env("artifacts/bench/run.jsonl");
133/// let _ = path;
134/// ```
135pub fn init_ailloli_ui_bench_from_env(default_path: &str) -> Option<std::path::PathBuf> {
136 ailloli_ui_bench::init_from_env(default_path)
137}
138pub use ailloli_ui_bench::{BenchInitError, BenchWriteError, CompletedRun};
139pub use capture::{
140 crop_captured_frame, strip_png_if_disabled, CaptureError, CaptureHandle, CaptureRequest,
141 CaptureRequestId, CaptureResult, CaptureTarget, FrameCaptureHook, FrameCaptureResult,
142};
143pub use event_loop::{new_event_loop, new_event_loop_allow_any_thread, run_app_on_event_loop};
144pub use external_url::SystemExternalUrlOpener;
145pub use host::{run_winit_host, HostDriver, HostOutcome, NoopHostDriver, WinitHost};
146#[cfg(feature = "native_overlay")]
147pub use native_overlay::{
148 NativeCalibrationMarkerGuard, NativeCalibrationMarkerPixel, NativeCalibrationMarkerSpec,
149 NativeOutputDescriptor, NativeOutputProbeService, NativeOutputScale, NativeOutputTransform,
150 NativeOverlayBackend, NativeOverlayCapabilities, NativeOverlayError, NativeOverlayInputMode,
151 NativeOverlayOptions, NativeOverlayRect, NativeOverlayTarget,
152};
153#[cfg(feature = "test_support")]
154pub use ui_app::{PresentationTestFault, PresentationTestState};
155pub use ui_app::{UiApp, UiAppError};
156pub use wgpu_bootstrap::{
157 detach_renderer_surface, reattach_renderer_to_window, renderer_from_window,
158 renderer_from_window_with_options,
159};
160pub use window::{create_window, create_window_before_run, window_attributes, WindowOptions};
161
162/// Popup backends available from the current winit adapter.
163///
164/// Winit 0.30 has no validated native popup path in Ailloli UI, so this
165/// adapter deliberately advertises only the universal retained overlay. A
166/// future native capability must pass the platform matrix before changing
167/// this value.
168///
169/// # Examples
170///
171/// ```
172/// use ailloli_ui_runtime::popup::PopupBackend;
173/// let capabilities = ailloli_ui_winit::popup_backend_capabilities();
174/// assert!(capabilities.supports(PopupBackend::Overlay));
175/// assert!(!capabilities.supports(PopupBackend::Native));
176/// ```
177pub const fn popup_backend_capabilities() -> ailloli_ui_runtime::popup::PopupBackendCapabilities {
178 ailloli_ui_runtime::popup::PopupBackendCapabilities::overlay_only()
179}
180
181#[cfg(test)]
182/// Capability regression ensuring winit 0.30 remains overlay-only.
183mod popup_backend_tests {
184 use ailloli_ui_runtime::popup::PopupBackend;
185
186 #[test]
187 fn winit_030_does_not_advertise_native_popups() {
188 let capabilities = super::popup_backend_capabilities();
189 assert!(capabilities.supports(PopupBackend::Overlay));
190 assert!(!capabilities.supports(PopupBackend::Native));
191 }
192}