onedrop_gui/

main.rs

//! OneDrop GUI - Graphical user interface for MilkDrop visualizations

mod keymap;
mod options_ui;
mod settings;

use anyhow::Result;
use clap::Parser;
use keymap::{Action, Binding, Keymap, Modifiers};
use onedrop_engine::{
    AudioInput, BeatDetectionMode, EngineConfig, MilkEngine, PresetChange, PresetManager,
    RenderConfig, SelectionMode,
};
use options_ui::{HudData, OptionsActions, OptionsUi};
use settings::{PresetSelectionMode, Settings, data_path};
use std::path::PathBuf;
use std::sync::Arc;
use std::time::Instant;
use winit::{
    application::ApplicationHandler,
    event::*,
    event_loop::{ActiveEventLoop, ControlFlow, EventLoop},
    keyboard::{KeyCode, PhysicalKey},
    window::{Fullscreen, Window, WindowId},
};

/// Command-line arguments for `onedrop-gui`.
#[derive(Parser, Debug)]
#[command(
    name = "onedrop-gui",
    about = "OneDrop — a pure-Rust MilkDrop visualizer",
    long_about = None,
    version,
)]
struct Args {
    /// Directory to scan for `.milk` presets. May be repeated. If omitted,
    /// OneDrop searches `$XDG_CONFIG_HOME/onedrop/presets/`, then a `presets/`
    /// folder next to the binary, then a `test-presets/` folder in the
    /// repository (dev convenience).
    #[arg(long = "preset-dir", short = 'd', value_name = "DIR")]
    preset_dirs: Vec<PathBuf>,

    /// Load a single `.milk` file directly. Overrides directory search.
    #[arg(long = "preset", short = 'p', value_name = "FILE")]
    preset: Option<PathBuf>,

    /// Start the window in fullscreen mode.
    #[arg(long, short = 'f')]
    fullscreen: bool,

    /// Window width (ignored if `--fullscreen`).
    #[arg(long, default_value_t = 1280)]
    width: u32,

    /// Window height (ignored if `--fullscreen`).
    #[arg(long, default_value_t = 720)]
    height: u32,

    /// Disable vsync (uncapped frame rate). Useful for benchmarking — the
    /// default is vsync ON so the GUI runs at monitor refresh.
    #[arg(long)]
    no_vsync: bool,
}

/// Discover preset files. Honours `--preset` first, then `--preset-dir`
/// (one or more), then the default search path. Returns the list of
/// `.milk` files found, in lexicographic order so the boot sequence is
/// reproducible.
fn discover_presets(args: &Args) -> Vec<PathBuf> {
    if let Some(p) = &args.preset {
        return vec![p.clone()];
    }

    let mut dirs: Vec<PathBuf> = args.preset_dirs.clone();
    if dirs.is_empty() {
        if let Some(cfg) = dirs::config_dir() {
            dirs.push(cfg.join("onedrop").join("presets"));
        }
        if let Ok(exe) = std::env::current_exe()
            && let Some(parent) = exe.parent()
        {
            dirs.push(parent.join("presets"));
        }
        // Distro packages install presets here.
        dirs.push(PathBuf::from("/usr/share/onedrop/presets"));
        dirs.push(PathBuf::from("/usr/local/share/onedrop/presets"));
        // Dev convenience: workspace-root and cwd-relative locations.
        dirs.push(PathBuf::from("test-presets"));
        dirs.push(PathBuf::from("../test-presets"));
    }

    let mut out: Vec<PathBuf> = Vec::new();
    for d in &dirs {
        if let Ok(entries) = std::fs::read_dir(d) {
            log::info!("Scanning preset directory: {}", d.display());
            for entry in entries.flatten() {
                let path = entry.path();
                if path.extension().and_then(|s| s.to_str()) == Some("milk") {
                    out.push(path);
                }
            }
        }
    }
    out.sort();
    out
}

/// Fullscreen-triangle blit that samples the engine's final display texture
/// and writes to the swapchain. Sampling (rather than `copy_texture_to_texture`)
/// sidesteps two failure modes: it doesn't need `COPY_DST` on the swapchain
/// (not guaranteed on all platforms), and sRGB conversion happens automatically
/// when source and destination formats disagree.
struct Blit {
    pipeline: wgpu::RenderPipeline,
    bind_group_layout: wgpu::BindGroupLayout,
    sampler: wgpu::Sampler,
}

impl Blit {
    fn new(device: &wgpu::Device, target_format: wgpu::TextureFormat) -> Self {
        let shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
            label: Some("Blit Shader"),
            source: wgpu::ShaderSource::Wgsl(
                r#"
@vertex
fn vs_main(@builtin(vertex_index) vid: u32) -> @builtin(position) vec4<f32> {
    // Fullscreen triangle covering the viewport.
    var p = array<vec2<f32>, 3>(
        vec2<f32>(-1.0, -3.0),
        vec2<f32>(-1.0,  1.0),
        vec2<f32>( 3.0,  1.0),
    );
    return vec4<f32>(p[vid], 0.0, 1.0);
}

@group(0) @binding(0) var t: texture_2d<f32>;
@group(0) @binding(1) var s: sampler;

@fragment
fn fs_main(@builtin(position) frag: vec4<f32>) -> @location(0) vec4<f32> {
    let dims = vec2<f32>(textureDimensions(t, 0));
    let uv = vec2<f32>(frag.x / dims.x, frag.y / dims.y);
    return textureSample(t, s, uv);
}
"#
                .into(),
            ),
        });

        let bind_group_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            label: Some("Blit BGL"),
            entries: &[
                wgpu::BindGroupLayoutEntry {
                    binding: 0,
                    visibility: wgpu::ShaderStages::FRAGMENT,
                    ty: wgpu::BindingType::Texture {
                        sample_type: wgpu::TextureSampleType::Float { filterable: true },
                        view_dimension: wgpu::TextureViewDimension::D2,
                        multisampled: false,
                    },
                    count: None,
                },
                wgpu::BindGroupLayoutEntry {
                    binding: 1,
                    visibility: wgpu::ShaderStages::FRAGMENT,
                    ty: wgpu::BindingType::Sampler(wgpu::SamplerBindingType::Filtering),
                    count: None,
                },
            ],
        });

        let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
            label: Some("Blit Pipeline Layout"),
            bind_group_layouts: &[Some(&bind_group_layout)],
            immediate_size: 0,
        });

        let pipeline = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
            label: Some("Blit Pipeline"),
            layout: Some(&pipeline_layout),
            vertex: wgpu::VertexState {
                module: &shader,
                entry_point: Some("vs_main"),
                buffers: &[],
                compilation_options: Default::default(),
            },
            fragment: Some(wgpu::FragmentState {
                module: &shader,
                entry_point: Some("fs_main"),
                targets: &[Some(wgpu::ColorTargetState {
                    format: target_format,
                    blend: None,
                    write_mask: wgpu::ColorWrites::ALL,
                })],
                compilation_options: Default::default(),
            }),
            primitive: wgpu::PrimitiveState {
                topology: wgpu::PrimitiveTopology::TriangleList,
                ..Default::default()
            },
            depth_stencil: None,
            multisample: wgpu::MultisampleState::default(),
            multiview_mask: None,
            cache: None,
        });

        let sampler = device.create_sampler(&wgpu::SamplerDescriptor {
            label: Some("Blit Sampler"),
            address_mode_u: wgpu::AddressMode::ClampToEdge,
            address_mode_v: wgpu::AddressMode::ClampToEdge,
            address_mode_w: wgpu::AddressMode::ClampToEdge,
            mag_filter: wgpu::FilterMode::Linear,
            min_filter: wgpu::FilterMode::Linear,
            mipmap_filter: wgpu::MipmapFilterMode::Nearest,
            ..Default::default()
        });

        Self {
            pipeline,
            bind_group_layout,
            sampler,
        }
    }
}

struct App {
    window: Option<Arc<Window>>,
    surface: Option<wgpu::Surface<'static>>,
    surface_config: Option<wgpu::SurfaceConfiguration>,
    device: Option<Arc<wgpu::Device>>,
    queue: Option<Arc<wgpu::Queue>>,
    engine: Option<MilkEngine>,
    audio_input: Option<AudioInput>,
    blit: Option<Blit>,
    preset_manager: PresetManager,
    last_frame: Instant,
    frame_count: u32,
    /// Window-creation preferences read once from CLI args.
    initial_width: u32,
    initial_height: u32,
    fullscreen: bool,
    no_vsync: bool,
    /// Timestamp of the last left-click; used to detect double-click.
    last_left_click: Option<Instant>,
    /// Start of the current FPS-measurement window.
    fps_window_start: Instant,
    /// Frames rendered since `fps_window_start`.
    fps_window_frames: u32,
    /// Last computed FPS (refreshed every ~2s alongside the log). Fed
    /// into the HUD overlay.
    last_fps: f32,
    /// Timestamp of the last cursor movement. Drives the auto-hide
    /// behaviour (`Settings::window::cursor_auto_hide_secs`).
    last_cursor_move: Instant,
    /// Current visibility of the cursor — mirrors what we last told
    /// winit so we don't spam `set_cursor_visible` on every frame.
    cursor_visible: bool,
    /// Persistent settings loaded at startup; the Options overlay
    /// edits this in place and re-saves on every change.
    settings: Settings,
    /// egui-based Options overlay. `None` until `init_graphics` runs.
    options_ui: Option<OptionsUi>,
    /// Current modifier state, kept in sync with
    /// `WindowEvent::ModifiersChanged`. The sprite + message
    /// keybindings (§5, §6) read `Shift` (random sprite) and `Ctrl`
    /// (clear all) from here.
    modifiers: winit::event::Modifiers,
    /// Keybind table. Defaults to MD2-style mapping; overrides come
    /// from `~/.config/onedrop/settings.toml` `[keymap.bindings]`.
    keymap: Keymap,
}

impl App {
    fn new(args: &Args, settings: Settings) -> Self {
        let mut preset_manager =
            PresetManager::with_history_size(settings.presets.history_size.max(1));
        preset_manager.set_locked(settings.presets.locked);
        preset_manager.set_mode(match settings.presets.mode {
            PresetSelectionMode::Random => SelectionMode::Random,
            PresetSelectionMode::Sequential => SelectionMode::Sequential,
        });
        // Persisted ratings live alongside history/state in the XDG
        // data dir. Missing file → no-op; the manager just runs with
        // an empty rating map and persists on the next nudge.
        if let Some(p) = data_path("ratings.toml") {
            preset_manager.attach_ratings_file(p);
        }

        let keymap = Keymap::from_settings(&settings.keymap);

        let presets = discover_presets(args);
        if presets.is_empty() {
            log::warn!(
                "No `.milk` presets found. Pass `--preset-dir <DIR>` or drop \
                 presets into `~/.config/onedrop/presets/`. Starting with the \
                 built-in default preset only."
            );
        } else {
            log::info!("Loaded {} preset(s)", presets.len());
            for p in presets {
                preset_manager.add_preset(p);
            }
        }

        // Prefer the device the user last picked, when one is saved.
        // Falls back to OS default (and finally demo audio) the same
        // way the no-config path always has.
        let preferred_device = settings.audio.input_device.as_deref();
        let audio_input = match AudioInput::with_device(preferred_device) {
            Ok(input) => {
                log::info!(
                    "Real audio input initialized (requested device: {:?})",
                    preferred_device.unwrap_or("Default")
                );
                Some(input)
            }
            Err(e) => {
                log::warn!(
                    "Failed to initialize audio input: {}. Falling back to demo mode.",
                    e
                );
                None
            }
        };
        Self {
            window: None,
            surface: None,
            surface_config: None,
            device: None,
            queue: None,
            engine: None,
            audio_input,
            blit: None,
            preset_manager,
            last_frame: Instant::now(),
            frame_count: 0,
            initial_width: args.width,
            initial_height: args.height,
            fullscreen: args.fullscreen,
            no_vsync: args.no_vsync,
            last_left_click: None,
            fps_window_start: Instant::now(),
            fps_window_frames: 0,
            last_fps: 0.0,
            last_cursor_move: Instant::now(),
            cursor_visible: true,
            settings,
            options_ui: None,
            modifiers: winit::event::Modifiers::default(),
            keymap,
        }
    }

    fn toggle_fullscreen(&self) {
        if let Some(window) = &self.window {
            if window.fullscreen().is_some() {
                window.set_fullscreen(None);
            } else {
                window.set_fullscreen(Some(Fullscreen::Borderless(None)));
            }
        }
    }

    fn init_graphics(&mut self, window: Arc<Window>) -> Result<()> {
        let size = window.inner_size();

        // Create wgpu instance (wgpu 29: InstanceDescriptor lost Default).
        let instance = wgpu::Instance::new(wgpu::InstanceDescriptor {
            backends: wgpu::Backends::all(),
            ..wgpu::InstanceDescriptor::new_without_display_handle()
        });

        // Create surface
        let surface = instance.create_surface(window.clone())?;

        // Request adapter — wgpu 29 returns Result<Adapter, RequestAdapterError>.
        let adapter = pollster::block_on(instance.request_adapter(&wgpu::RequestAdapterOptions {
            power_preference: wgpu::PowerPreference::HighPerformance,
            compatible_surface: Some(&surface),
            force_fallback_adapter: false,
        }))
        .map_err(|e| anyhow::anyhow!("Failed to find adapter: {e}"))?;

        // Request device and queue — single-arg in wgpu 29; new fields on DeviceDescriptor.
        // Match `GpuContext::new`: the comp pass binds up to 18 sampled textures
        // (main + 3 blur + 3 noise 2D + 2 noise 3D + 8 user-slot + 1 prev) so the
        // wgpu default of 16 panics on bind-group creation. 24 leaves headroom.
        let (device, queue) =
            pollster::block_on(adapter.request_device(&wgpu::DeviceDescriptor {
                label: Some("Device"),
                required_features: wgpu::Features::empty(),
                required_limits: wgpu::Limits {
                    max_sampled_textures_per_shader_stage: 24,
                    ..wgpu::Limits::default()
                },
                memory_hints: Default::default(),
                experimental_features: wgpu::ExperimentalFeatures::default(),
                trace: wgpu::Trace::Off,
            }))?;

        let device = Arc::new(device);
        let queue = Arc::new(queue);

        // Configure surface
        let surface_caps = surface.get_capabilities(&adapter);
        let surface_format = surface_caps
            .formats
            .iter()
            .find(|f| f.is_srgb())
            .copied()
            .unwrap_or(surface_caps.formats[0]);

        // Vsync default: Fifo (capped at refresh rate). `--no-vsync` switches
        // to Immediate (uncapped, with tearing — for benchmarking) and falls
        // back to Mailbox if the platform doesn't expose Immediate.
        let present_mode = if self.no_vsync {
            let caps = surface_caps.present_modes.as_slice();
            if caps.contains(&wgpu::PresentMode::Immediate) {
                wgpu::PresentMode::Immediate
            } else if caps.contains(&wgpu::PresentMode::Mailbox) {
                wgpu::PresentMode::Mailbox
            } else {
                wgpu::PresentMode::Fifo
            }
        } else {
            wgpu::PresentMode::Fifo
        };

        // The blit pass writes through the default sRGB view (preserves
        // current colour-correct compositing of the MilkDrop output),
        // but egui prefers a linear target — feeding its already-gamma-
        // encoded output into an sRGB view double-encodes and darkens
        // every widget. Declare the matching non-sRGB format as an
        // alternate view so the egui pass can target it on the same
        // swapchain texture without a separate framebuffer.
        let linear_view_format = surface_format.remove_srgb_suffix();
        let view_formats = if linear_view_format != surface_format {
            vec![linear_view_format]
        } else {
            vec![]
        };
        let config = wgpu::SurfaceConfiguration {
            usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
            format: surface_format,
            width: size.width,
            height: size.height,
            present_mode,
            alpha_mode: surface_caps.alpha_modes[0],
            view_formats,
            desired_maximum_frame_latency: 2,
        };

        surface.configure(&device, &config);

        // Create engine with shared device, seeded by persisted settings.
        let engine_config = EngineConfig {
            render_config: RenderConfig {
                width: size.width,
                height: size.height,
                mesh_cols: self.settings.visuals.mesh_cols,
                mesh_rows: self.settings.visuals.mesh_rows,
                vsync: self.settings.visuals.vsync,
                target_fps: self.settings.visuals.target_fps,
                msaa_samples: self.settings.visuals.msaa_samples,
                ..Default::default()
            },
            enable_per_frame: self.settings.engine.enable_per_frame,
            transition_duration_s: self.settings.engine.transition_duration_s,
            profile: self.settings.engine.profile,
            ..Default::default()
        };

        // Share device and queue with engine
        let mut engine =
            MilkEngine::from_device(Arc::clone(&device), Arc::clone(&queue), engine_config)?;

        // Apply persisted beat-detection mode. The engine boots with
        // `Off`; `set_beat_detection_mode` is the same path the F8
        // cycle and the Options panel use.
        let beat_mode = beat_mode_from_name(&self.settings.playback.beat_detection_mode);
        engine.set_beat_detection_mode(beat_mode);

        // Build the blit pass that samples the engine's final texture into the
        // swapchain — see `Blit` for why this exists.
        let blit = Blit::new(&device, surface_format);

        // egui Options overlay — renders on top of the blit each frame.
        // Use the non-sRGB view format so egui's gamma encoding lands
        // on a linear target (see `linear_view_format` above). The
        // boot-settings snapshot lets the UI detect when a restart is
        // needed (MSAA, texture format).
        let options_ui =
            OptionsUi::new(&window, &device, linear_view_format, self.settings.clone());

        window.set_title("OneDrop");

        self.window = Some(window);
        self.surface = Some(surface);
        self.surface_config = Some(config);
        self.device = Some(device);
        self.queue = Some(queue);
        self.engine = Some(engine);
        self.blit = Some(blit);
        self.options_ui = Some(options_ui);

        // Load first preset if available
        if let Some(preset_path) = self.preset_manager.current_preset()
            && let Some(engine) = &mut self.engine
        {
            if let Err(e) = engine.load_preset(preset_path) {
                log::error!("Failed to load preset: {}", e);
            } else {
                log::info!("Loaded preset: {}", preset_path.display());
            }
        }

        Ok(())
    }

    fn render(&mut self) -> Result<()> {
        let surface = self
            .surface
            .as_ref()
            .ok_or_else(|| anyhow::anyhow!("Graphics not initialized: surface"))?;
        let device = self
            .device
            .as_ref()
            .ok_or_else(|| anyhow::anyhow!("Graphics not initialized: device"))?;
        let queue = self
            .queue
            .as_ref()
            .ok_or_else(|| anyhow::anyhow!("Graphics not initialized: queue"))?;
        let engine = self
            .engine
            .as_mut()
            .ok_or_else(|| anyhow::anyhow!("Graphics not initialized: engine"))?;

        // Calculate delta time
        let now = Instant::now();
        let delta_time = (now - self.last_frame).as_secs_f32();
        self.last_frame = now;

        // Get audio samples - use real audio input or fall back to demo mode
        let audio_samples: Vec<f32> = if let Some(ref audio_input) = self.audio_input {
            // Use real audio capture
            audio_input.get_fixed_samples(1024)
        } else {
            // Fallback: generate demo audio (sine wave)
            (0..1024)
                .map(|i| {
                    let t = (self.frame_count * 1024 + i) as f32 * 0.001;
                    (t * 2.0 * std::f32::consts::PI * 60.0).sin() * 0.5
                })
                .collect()
        };

        // Update engine
        let preset_change = engine.update(&audio_samples, delta_time)?;

        // Handle automatic preset change from beat detection
        if let Some(change) = preset_change {
            match change {
                PresetChange::Random => {
                    // Load random preset
                    if let Some(preset_path) = self.preset_manager.random_preset() {
                        if let Err(e) = engine.load_preset(preset_path) {
                            log::error!("Failed to load random preset: {}", e);
                        } else {
                            log::info!(
                                "Beat detection: Loaded random preset: {}",
                                preset_path.display()
                            );
                        }
                    }
                }
                PresetChange::Specific(path) => {
                    // Load specific preset
                    if let Err(e) = engine.load_preset(&path) {
                        log::error!("Failed to load specific preset {}: {}", path, e);
                    } else {
                        log::info!("Beat detection: Loaded specific preset: {}", path);
                    }
                }
            }
        }

        // Get surface texture — wgpu 29 returns CurrentSurfaceTexture (enum),
        // not Result. Treat non-Success states as "skip this frame".
        let output = match surface.get_current_texture() {
            wgpu::CurrentSurfaceTexture::Success(t) => t,
            wgpu::CurrentSurfaceTexture::Suboptimal(t) => {
                log::debug!("Surface texture suboptimal — reconfigure recommended");
                t
            }
            other => {
                log::debug!("Surface texture unavailable ({other:?}) — skipping frame");
                return Ok(());
            }
        };
        let view = output
            .texture
            .create_view(&wgpu::TextureViewDescriptor::default());

        let blit = self
            .blit
            .as_ref()
            .ok_or_else(|| anyhow::anyhow!("Graphics not initialized: blit"))?;

        // Sample the engine's final texture into the swapchain via a
        // fullscreen-triangle blit (handles format mismatch automatically).
        let src_view = engine
            .renderer()
            .render_texture()
            .create_view(&wgpu::TextureViewDescriptor::default());
        let bind_group = device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("Blit Bind Group"),
            layout: &blit.bind_group_layout,
            entries: &[
                wgpu::BindGroupEntry {
                    binding: 0,
                    resource: wgpu::BindingResource::TextureView(&src_view),
                },
                wgpu::BindGroupEntry {
                    binding: 1,
                    resource: wgpu::BindingResource::Sampler(&blit.sampler),
                },
            ],
        });

        let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
            label: Some("Render Encoder"),
        });
        {
            let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
                label: Some("Blit Pass"),
                color_attachments: &[Some(wgpu::RenderPassColorAttachment {
                    view: &view,
                    resolve_target: None,
                    ops: wgpu::Operations {
                        load: wgpu::LoadOp::Clear(wgpu::Color::BLACK),
                        store: wgpu::StoreOp::Store,
                    },
                    depth_slice: None,
                })],
                depth_stencil_attachment: None,
                timestamp_writes: None,
                occlusion_query_set: None,
                multiview_mask: None,
            });
            pass.set_pipeline(&blit.pipeline);
            pass.set_bind_group(0, &bind_group, &[]);
            pass.draw(0..3, 0..1);
        }

        // egui Options overlay — composites on top of the blit when
        // `options_ui.visible == true`, no-op otherwise. Apply any
        // changes the user made this frame to the live engine, and
        // re-save settings.
        //
        // egui targets a non-sRGB view of the same swapchain texture
        // so its already-gamma-encoded output isn't double-encoded by
        // the hardware sRGB write. The blit pass continues to use the
        // default sRGB view.
        let actions = if let (Some(ui), Some(win), Some(cfg)) =
            (&mut self.options_ui, &self.window, &self.surface_config)
        {
            let linear_format = cfg.format.remove_srgb_suffix();
            let egui_view = output.texture.create_view(&wgpu::TextureViewDescriptor {
                label: Some("egui Linear View"),
                format: Some(linear_format),
                ..Default::default()
            });
            let preset_name = self
                .preset_manager
                .current_preset()
                .and_then(|p| p.file_stem())
                .and_then(|s| s.to_str())
                .unwrap_or("")
                .to_string();
            let (cols, rows) = engine.renderer().mesh_size();
            let hud = HudData {
                fps: self.last_fps,
                preset_name,
                mesh_cols: cols,
                mesh_rows: rows,
            };
            ui.render(
                device,
                queue,
                win,
                &mut encoder,
                &egui_view,
                (cfg.width, cfg.height),
                &mut self.settings,
                &hud,
            )
        } else {
            OptionsActions::default()
        };
        if actions.any() {
            apply_options_actions(engine, &actions);
            self.settings.save();
        }

        queue.submit(std::iter::once(encoder.finish()));
        self.window
            .as_ref()
            .ok_or_else(|| anyhow::anyhow!("Graphics not initialized: window"))?
            .pre_present_notify();
        output.present();

        // Deferred Options-panel side-effects: anything that needs
        // `&mut self` runs after the queue borrow is released and the
        // current frame has shipped.
        if let Some(vsync) = actions.vsync {
            self.reconfigure_present_mode(vsync);
        }
        if let Some(ref device_choice) = actions.audio_device {
            self.swap_audio_input(device_choice.as_deref());
        }
        if actions.request_restart {
            relaunch_self();
        }

        self.frame_count += 1;
        self.fps_window_frames += 1;
        let elapsed = self.fps_window_start.elapsed();
        if elapsed.as_secs_f32() >= 2.0 {
            let fps = self.fps_window_frames as f32 / elapsed.as_secs_f32();
            self.last_fps = fps;
            let (w, h) = self
                .surface_config
                .as_ref()
                .map(|c| (c.width, c.height))
                .unwrap_or((0, 0));
            log::info!("{:.1} fps @ {w}x{h}", fps);
            self.fps_window_start = Instant::now();
            self.fps_window_frames = 0;
        }

        // Cursor auto-hide. The HUD doesn't care about input, so we
        // can safely hide the cursor while the panel is closed too.
        // Setting visibility on every frame would be a no-op syscall
        // but we track our last desired state to avoid the redundancy.
        let auto_hide = self.settings.window.cursor_auto_hide_secs;
        if auto_hide > 0.0
            && let Some(window) = &self.window
        {
            let want_visible =
                self.options_open() || self.last_cursor_move.elapsed().as_secs_f32() < auto_hide;
            if want_visible != self.cursor_visible {
                window.set_cursor_visible(want_visible);
                self.cursor_visible = want_visible;
            }
        }

        Ok(())
    }

    /// Drop the active audio capture stream and rebuild it against a
    /// different cpal device. `name = None` means "the OS default";
    /// a name that doesn't match any current device falls back to the
    /// default with a warning logged by the engine helper.
    fn swap_audio_input(&mut self, name: Option<&str>) {
        // Drop the previous stream first so we don't briefly hold two
        // simultaneous captures on the same device.
        self.audio_input = None;
        match AudioInput::with_device(name) {
            Ok(input) => {
                log::info!("Audio input switched to {:?}", name.unwrap_or("Default"));
                self.audio_input = Some(input);
            }
            Err(e) => {
                log::warn!("Failed to open audio input {:?}: {e}", name);
            }
        }
    }

    /// Reconfigure the swapchain for a new VSync preference. Mirrors
    /// the boot logic in `init_graphics` for picking a present mode:
    /// `Fifo` for VSync ON, `Immediate` (with `Mailbox` fallback) for
    /// OFF. Called by the Options panel.
    fn reconfigure_present_mode(&mut self, vsync: bool) {
        let (Some(surface), Some(device), Some(cfg)) = (
            self.surface.as_ref(),
            self.device.as_ref(),
            self.surface_config.as_mut(),
        ) else {
            return;
        };
        let new_mode = if vsync {
            wgpu::PresentMode::Fifo
        } else {
            // We can't re-query the adapter's present-mode capabilities
            // here without plumbing them; assume Immediate is supported
            // on the systems where the user would actually flip this
            // switch. Falling back to Mailbox is a marginal upgrade
            // anyway.
            wgpu::PresentMode::Immediate
        };
        if cfg.present_mode == new_mode {
            return;
        }
        cfg.present_mode = new_mode;
        surface.configure(device, cfg);
        log::info!("Present mode → {:?}", new_mode);
        self.no_vsync = !vsync;
    }

    /// Return true when the Options overlay is currently drawn on
    /// screen. Used by `handle_keyboard` to scope the Esc key to
    /// "close overlay" rather than "quit" while the panel is open.
    fn options_open(&self) -> bool {
        self.options_ui.as_ref().is_some_and(|ui| ui.visible)
    }

    fn handle_keyboard(&mut self, event_loop: &ActiveEventLoop, key_code: KeyCode) {
        let mods = Modifiers::from_winit(self.modifiers.state());
        let binding = Binding::new(key_code, mods);
        let Some(action) = self.keymap.lookup(binding) else {
            return;
        };

        // Tab / Esc-while-options-open are global — they take priority
        // over the options-overlay suppression below.
        match action {
            Action::ToggleOptions => {
                if let Some(ui) = &mut self.options_ui {
                    ui.toggle();
                }
                return;
            }
            Action::Quit if self.options_open() => {
                if let Some(ui) = &mut self.options_ui {
                    ui.visible = false;
                }
                return;
            }
            _ => {}
        }

        // Suppress preset/transport shortcuts when the overlay is open
        // so typing in widgets doesn't also flip presets.
        if self.options_open() {
            return;
        }

        self.dispatch_action(event_loop, action);
    }

    /// Run the side-effects for a resolved [`Action`]. Split out from
    /// `handle_keyboard` so the lookup → dispatch step is testable in
    /// isolation and so action handlers can be added without touching
    /// the winit event-decoding glue.
    fn dispatch_action(&mut self, event_loop: &ActiveEventLoop, action: Action) {
        match action {
            Action::NextPreset | Action::NextPresetInstant => {
                if let Some(path) = self.preset_manager.advance() {
                    if let Some(engine) = &mut self.engine {
                        if let Err(e) = engine.load_preset(&path) {
                            log::error!("Failed to load preset: {}", e);
                        } else {
                            log::info!("Loaded preset: {}", path.display());
                        }
                    }
                } else if self.preset_manager.is_locked() {
                    log::info!("Preset locked — change blocked. Press ScrollLock to unlock.");
                }
            }
            Action::PreviousPreset => {
                if let Some(path) = self.preset_manager.retreat() {
                    if let Some(engine) = &mut self.engine {
                        if let Err(e) = engine.load_preset(&path) {
                            log::error!("Failed to load preset: {}", e);
                        } else {
                            log::info!("Loaded preset (back): {}", path.display());
                        }
                    }
                } else if self.preset_manager.is_locked() {
                    log::info!("Preset locked — change blocked. Press ScrollLock to unlock.");
                }
            }
            Action::ToggleRandomMode => {
                let mode = self.preset_manager.cycle_mode();
                self.settings.presets.mode = match mode {
                    SelectionMode::Random => PresetSelectionMode::Random,
                    SelectionMode::Sequential => PresetSelectionMode::Sequential,
                };
                self.settings.save();
                log::info!("Selection mode: {:?}", mode);
            }
            Action::TogglePresetLock => {
                let locked = self.preset_manager.toggle_lock();
                self.settings.presets.locked = locked;
                self.settings.save();
                log::info!("Preset lock: {}", if locked { "ON" } else { "OFF" });
            }
            Action::EngineReset => {
                if let Some(engine) = &mut self.engine {
                    engine.reset();
                    log::info!("Engine reset");
                }
            }
            Action::RateUp | Action::RateDown => {
                let delta = if action == Action::RateUp { 1 } else { -1 };
                match self.preset_manager.nudge_current_rating(delta) {
                    Some(r) => log::info!(
                        "Rating: {} ({})",
                        r,
                        self.preset_manager
                            .current_preset()
                            .map(|p| p.display().to_string())
                            .unwrap_or_else(|| "<no preset>".into())
                    ),
                    None => log::info!("No current preset to rate"),
                }
            }
            Action::CycleBeatDetection => {
                if let Some(engine) = &mut self.engine {
                    engine.next_beat_detection_mode();
                    let mode = engine.beat_detector().mode();
                    log::info!("Beat detection mode: {}", mode.name());
                    let description = match mode {
                        BeatDetectionMode::Off => "Off - No automatic preset changes",
                        BeatDetectionMode::HardCut1 => {
                            "HardCut1 - Change on bass > 1.5 (delay 0.2s)"
                        }
                        BeatDetectionMode::HardCut2 => {
                            "HardCut2 - Change on treb > 2.9 (delay 0.5s)"
                        }
                        BeatDetectionMode::HardCut3 => "HardCut3 - Change on treb > 2.9 (delay 1s)",
                        BeatDetectionMode::HardCut4 => {
                            "HardCut4 - Change on treb > 2.9 (delay 3s) or treb > 8"
                        }
                        BeatDetectionMode::HardCut5 => "HardCut5 - Change on treb > 2.9 (delay 5s)",
                        BeatDetectionMode::HardCut6 { .. } => {
                            "HardCut6 - Change on bass > 1.5, special on bass > 4.90"
                        }
                    };
                    log::info!("  {}", description);
                    self.settings.playback.beat_detection_mode = mode.name().to_string();
                    self.settings.save();
                }
            }
            Action::SpriteCycle | Action::SpriteRandom => {
                if let Some(engine) = &mut self.engine {
                    let result = if action == Action::SpriteRandom {
                        let seed =
                            (engine.state().frame as u64) ^ (engine.state().time.to_bits() as u64);
                        engine.spawn_random_sprite(seed)
                    } else {
                        engine.cycle_next_sprite()
                    };
                    match result {
                        Some(slot) => log::info!(
                            "Sprite slot {} spawned (active={})",
                            slot,
                            engine.sprite_active_count()
                        ),
                        None => log::info!(
                            "No sprite defs loaded (drop a MILK_IMG.INI next to a preset)"
                        ),
                    }
                }
            }
            Action::SpritePopRecent => {
                if let Some(engine) = &mut self.engine {
                    let popped = engine.pop_most_recent_sprite();
                    if popped {
                        log::info!(
                            "Popped most recent sprite (active={})",
                            engine.sprite_active_count()
                        );
                    }
                }
            }
            Action::MessageCycle => {
                if let Some(engine) = &mut self.engine {
                    match engine.cycle_next_message() {
                        Some(slot) => log::info!("Message slot {} shown", slot),
                        None => log::info!(
                            "No message defs loaded (drop a MILK_MSG.INI next to a preset)"
                        ),
                    }
                }
            }
            Action::ClearAllOverlays => {
                if let Some(engine) = &mut self.engine {
                    engine.clear_sprites();
                    engine.clear_messages();
                    log::info!("Cleared all sprite + message overlays");
                }
            }
            Action::ClearMessages => {
                if let Some(engine) = &mut self.engine {
                    engine.clear_messages();
                    log::info!("Cleared all active messages");
                }
            }
            Action::ToggleFullscreen => {
                self.toggle_fullscreen();
            }
            Action::Quit => {
                log::info!("Quit requested");
                event_loop.exit();
            }
            // Placeholders: bound to keys for parity with MD2's table
            // but no engine API exists for them in v1.0. Logging keeps
            // them discoverable from the GUI without crashing.
            Action::LoadMenu
            | Action::EditMenu
            | Action::SavePreset
            | Action::ToggleMonitor
            | Action::MashUp
            | Action::CycleShaderLock
            | Action::ShowHelp
            | Action::ShowSongInfo
            | Action::ShowFps
            | Action::ShowPresetName
            | Action::ShowRating
            | Action::RereadIni
            | Action::ToggleAnaglyph3D
            | Action::WarpAmountDown
            | Action::WarpAmountUp
            | Action::RotationCcw
            | Action::RotationCw
            | Action::ZoomOut
            | Action::ZoomIn
            | Action::WarpSpeedDown
            | Action::WarpSpeedUp
            | Action::CycleWaveform
            | Action::WaveScaleDown
            | Action::WaveScaleUp
            | Action::WaveOpacityDown
            | Action::WaveOpacityUp => {
                log::info!("Action {:?} is not implemented yet (v1.0 stub)", action);
            }
            // Handled before the dispatch — should never reach here.
            Action::ToggleOptions => {}
        }
    }
}

impl ApplicationHandler for App {
    fn resumed(&mut self, event_loop: &ActiveEventLoop) {
        if self.window.is_none() {
            let mut window_attributes = Window::default_attributes()
                .with_title("OneDrop")
                .with_inner_size(winit::dpi::LogicalSize::new(
                    self.initial_width,
                    self.initial_height,
                ));
            if self.fullscreen {
                window_attributes =
                    window_attributes.with_fullscreen(Some(Fullscreen::Borderless(None)));
            }

            match event_loop.create_window(window_attributes) {
                Ok(window) => {
                    let window = Arc::new(window);
                    if let Err(e) = self.init_graphics(window) {
                        log::error!("Failed to initialize graphics: {}", e);
                        event_loop.exit();
                    }
                }
                Err(e) => {
                    log::error!("Failed to create window: {}", e);
                    event_loop.exit();
                }
            }
        }
    }

    fn window_event(
        &mut self,
        event_loop: &ActiveEventLoop,
        _window_id: WindowId,
        event: WindowEvent,
    ) {
        // Hand the event to the egui overlay first. When the overlay is
        // visible and egui claims the event (e.g., click in a widget),
        // we suppress our own handling so typing in egui doesn't also
        // flip presets or quit the app.
        if let (Some(ui), Some(win)) = (&mut self.options_ui, &self.window)
            && ui.on_event(win, &event)
        {
            return;
        }
        match event {
            WindowEvent::CloseRequested => {
                log::info!("Close requested");
                event_loop.exit();
            }
            WindowEvent::KeyboardInput {
                event:
                    KeyEvent {
                        physical_key: PhysicalKey::Code(key_code),
                        state: ElementState::Pressed,
                        ..
                    },
                ..
            } => {
                self.handle_keyboard(event_loop, key_code);
            }
            WindowEvent::ModifiersChanged(new) => {
                self.modifiers = new;
            }
            WindowEvent::CursorMoved { .. } => {
                self.last_cursor_move = Instant::now();
            }
            WindowEvent::MouseInput {
                button: MouseButton::Left,
                state: ElementState::Pressed,
                ..
            } => {
                // 500 ms is the de-facto double-click threshold on Linux DEs
                // (GTK's `gtk-double-click-time` defaults to 400, Qt's is 500).
                let now = Instant::now();
                let is_double = self
                    .last_left_click
                    .is_some_and(|prev| now.duration_since(prev).as_millis() < 500);
                self.last_left_click = Some(now);
                if is_double {
                    self.toggle_fullscreen();
                    // Reset so a third click doesn't read as another double.
                    self.last_left_click = None;
                }
            }
            WindowEvent::Resized(physical_size) => {
                if physical_size.width > 0
                    && physical_size.height > 0
                    && let (Some(surface), Some(device), Some(config)) =
                        (&self.surface, &self.device, &mut self.surface_config)
                {
                    config.width = physical_size.width;
                    config.height = physical_size.height;
                    surface.configure(device, config);

                    if let Some(engine) = &mut self.engine {
                        engine.resize(physical_size.width, physical_size.height);
                    }
                }
            }
            WindowEvent::RedrawRequested => {
                if let Err(e) = self.render() {
                    log::error!("Render error: {}", e);
                }

                if let Some(window) = &self.window {
                    window.request_redraw();
                }
            }
            _ => {}
        }
    }
}

/// Apply one frame's worth of Options-panel changes to the live
/// engine. Each field of [`OptionsActions`] is `Some` only when the
/// user just moved that widget, so the function is a series of cheap
/// no-ops on quiet frames.
///
/// Note: [`OptionsActions::vsync`] is handled by the caller because it
/// needs the surface, not the engine.
fn apply_options_actions(engine: &mut MilkEngine, actions: &OptionsActions) {
    if let Some((cols, rows)) = actions.mesh_size {
        engine.renderer_mut().set_mesh_size(cols, rows);
        log::info!("Mesh resized to {}×{}", cols, rows);
    }
    if let Some(d) = actions.transition_duration {
        engine.config_mut().transition_duration_s = d;
    }
    if let Some(b) = actions.enable_per_frame {
        engine.config_mut().enable_per_frame = b;
    }
    if let Some(b) = actions.profile {
        engine.config_mut().profile = b;
    }
    if let Some(mode) = actions.beat_detection_mode.clone() {
        log::info!("Beat detection mode → {}", mode.name());
        engine.set_beat_detection_mode(mode);
    }
}

/// Parse a beat-detection mode name (matches the Options-panel
/// dropdown and the engine's `BeatDetectionMode::name()`). Unknown
/// values map to `Off`, which is also the engine's boot default.
fn beat_mode_from_name(name: &str) -> BeatDetectionMode {
    match name {
        "HardCut1" => BeatDetectionMode::HardCut1,
        "HardCut2" => BeatDetectionMode::HardCut2,
        "HardCut3" => BeatDetectionMode::HardCut3,
        "HardCut4" => BeatDetectionMode::HardCut4,
        "HardCut5" => BeatDetectionMode::HardCut5,
        "HardCut6" => BeatDetectionMode::HardCut6 {
            special_preset: String::new(),
        },
        _ => BeatDetectionMode::Off,
    }
}

/// Spawn a fresh copy of the current binary with the same CLI args
/// and exit. Used by the Options panel's "Apply & restart" button so
/// settings that can't be applied live (MSAA, texture format) take
/// effect on the next boot. We rely on the caller having just called
/// `Settings::save()` so the new process reads the user's edits.
fn relaunch_self() {
    log::info!("Restarting to apply settings…");
    let exe = match std::env::current_exe() {
        Ok(p) => p,
        Err(e) => {
            log::error!("Failed to locate current executable: {e}");
            return;
        }
    };
    let args: Vec<String> = std::env::args().skip(1).collect();
    match std::process::Command::new(&exe).args(&args).spawn() {
        Ok(_) => std::process::exit(0),
        Err(e) => log::error!("Failed to relaunch {}: {e}", exe.display()),
    }
}

fn main() -> Result<()> {
    let args = Args::parse();

    env_logger::Builder::from_default_env()
        .filter_level(log::LevelFilter::Info)
        .init();

    log::info!("Starting OneDrop GUI...");
    log::info!(
        "Keys: N/→ next preset · P/← prev preset · R reset · F8 cycle beat-detect · Tab options · F11 fullscreen · Esc/Q quit"
    );

    let event_loop = EventLoop::new()?;
    event_loop.set_control_flow(ControlFlow::Poll);

    let settings = Settings::load();
    let mut app = App::new(&args, settings);

    event_loop.run_app(&mut app)?;

    Ok(())
}