onedrop_engine/

engine.rs

//! Main Milkdrop engine implementation.
//!
//! The `update()` orchestrator lives here; the three heavyweight per-frame
//! phases that used to dominate the file are split into sibling modules,
//! each adding its own `impl MilkEngine` block:
//!
//! - [`wave_phase`] — `evaluate_custom_waves`
//! - [`shape_phase`] — `evaluate_custom_shapes`
//! - [`state_sync`] — `update_render_state_from_evaluator`
//!
//! That split keeps `engine.rs` focused on the lifecycle (`new`, `load_preset`,
//! `update`, public getters) and supports preset transitions, where two engine
//! instances drive the wave/shape paths in parallel.

mod morph;
mod preset_slot;
mod shape_phase;
mod state_sync;
mod transition_state;
mod wave_phase;

use crate::audio::AudioAnalyzer;
use crate::beat_detection::{BeatDetectionMode, BeatDetector, PresetChange};
use crate::error::{EngineError, Result};
use crate::fft::FFTAnalyzer;
use onedrop_eval::{MilkEvaluator, Node};
use onedrop_parser::{MilkPreset, parse_preset};
use onedrop_renderer::{GpuContext, MilkRenderer, RenderConfig, RenderState};
use preset_slot::{CompiledShape, CompiledWave, PresetSlot, preset_id_for, run_block_with_logger};
use std::fs;
use std::path::Path;
use std::sync::Arc;
use std::time::{Duration, Instant};
use transition_state::TransitionState;
use wgpu;

/// Per-phase wall-clock breakdown for one `MilkEngine::update` call.
/// Populated when `EngineConfig::profile` is `true`; exposed by
/// `MilkEngine::last_profile()` for the bench tool and any future overlay.
#[derive(Debug, Default, Clone)]
pub struct FrameProfile {
    pub audio_analyze: Duration,
    pub spectrum_fft: Duration,
    pub per_frame_eval: Duration,
    pub state_sync: Duration,
    pub warp_compute: Duration,
    pub waveform_samples: Duration,
    pub custom_waves: Duration,
    pub custom_shapes: Duration,
    pub gpu_render: Duration,
    pub total: Duration,
}

/// FFT window size used to expose `value1`/`value2` spectrum bins to
/// `wavecode_N` per-point equations when `b_spectrum` is set. Power of 2,
/// large enough to give a reasonable bin density without ballooning the
/// analyzer cost. Matches the standard MD2 FFT size.
const SPECTRUM_FFT_SIZE: usize = 512;

/// Advance one slot's per-frame state: push the shared audio levels +
/// time + frame into its evaluator context, then run its per-frame
/// equations. Called once for `current` and (during transitions) once
/// for `fading_out` each frame.
///
/// `enable_per_frame == false` skips the equation eval but still updates
/// the context — keeps `time` / `audio` correct in case a downstream
/// path (warp executor, custom waves) reads them.
fn tick_slot_evaluator(
    slot: &mut PresetSlot,
    audio: onedrop_renderer::AudioLevels,
    delta_time: f32,
    enable_per_frame: bool,
    display_duration_s: f32,
    track_progress_override: Option<f32>,
) {
    slot.state.time += delta_time;
    slot.state.audio = audio;
    // MD2 `progress`: when an MPRIS player exposes a track position
    // (`ProgressSource::MprisAutoTrack` + a non-zero `mpris:length`),
    // the override replaces the local-window computation. Otherwise we
    // fall back to the per-preset display window: `display_duration_s
    // == 0` keeps `progress = 0` (window disabled); the per-preset
    // anchor in `slot.preset_loaded_time` recovers elapsed-since-load.
    slot.state.progress = match track_progress_override {
        Some(p) => p.clamp(0.0, 1.0),
        None if display_duration_s > 0.0 => {
            ((slot.state.time - slot.preset_loaded_time) / display_duration_s).clamp(0.0, 1.0)
        }
        None => 0.0,
    };

    let ctx = slot.evaluator.context_mut();
    ctx.set_time(slot.state.time as f64);
    ctx.set_frame(slot.state.frame as f64);
    // Expose `progress` to the per-frame evaluator context. MD2 preset
    // equations reference it directly (e.g., `wave_a = progress * 0.5`).
    ctx.set("progress", slot.state.progress as f64);
    ctx.set_audio(audio.bass as f64, audio.mid as f64, audio.treb as f64);
    ctx.set("bass_att", audio.bass_att as f64);
    ctx.set("mid_att", audio.mid_att as f64);
    ctx.set("treb_att", audio.treb_att as f64);

    if enable_per_frame {
        // Run the pre-compiled `per_frame` block. CompiledBlock prefers
        // the bytecode VM when its nodes lowered cleanly (~80 % of the
        // corpus), otherwise it falls back to the evalexpr Node walk —
        // either way we skip the regex-based reparse that the legacy
        // `eval_per_frame(&[String])` path was doing every call.
        // Populated at `load_preset`; empty (no-op) when no preset is
        // active.
        run_block_with_logger(&mut slot.evaluator, &slot.compiled_per_frame, |idx, e| {
            log::warn!("per_frame equation[{}] failed: {}", idx, e)
        });
    }
    // Frame counter is bumped by the engine after `renderer.render()` so
    // `comp_uniforms` for this frame still see the pre-tick value (matches
    // pre-V.3 ordering).
}

/// Main Milkdrop visualization engine.
pub struct MilkEngine {
    /// Renderer
    renderer: MilkRenderer,

    /// Active preset bundle: preset + evaluator + warp executor + state +
    /// compiled wave/shape equations.
    current: PresetSlot,

    /// Outgoing preset's bundle, alive only between a `load_preset` call
    /// and the moment the configured transition duration elapses. Driven
    /// each frame in lock-step with `current` so its warp / wave / shape
    /// outputs land on the renderer's secondary chain for the blend pass.
    fading_out: Option<PresetSlot>,

    /// Delta-time tracker for the in-flight transition. `None` outside
    /// transitions. Cleared in the same frame as `fading_out` once it
    /// reaches the configured duration.
    transition: Option<TransitionState>,

    /// Audio analyzer
    audio_analyzer: AudioAnalyzer,

    /// Beat detector for automatic preset changes
    beat_detector: BeatDetector,

    /// Engine configuration
    config: EngineConfig,

    /// Frequency-domain analyzer feeding `value1`/`value2` for
    /// `wavecode_N` blocks with `b_spectrum = 1`. Always populated each
    /// frame so the per-point loop pays no cost when no preset is active.
    fft: FFTAnalyzer,
    /// Spectrum magnitudes (size `SPECTRUM_FFT_SIZE / 2`) of the most
    /// recent audio buffer. Reused across waves within a frame.
    spectrum_bins: Vec<f32>,

    /// Wall-clock breakdown of the most recent `update` call. `None` when
    /// `EngineConfig::profile` is `false` (default). The bench tool flips
    /// it on; production builds leave it off to save the `Instant::now`
    /// reads (`Instant::elapsed` measured at ~20 ns × 9 phases = ~180 ns,
    /// negligible but trivially avoidable).
    last_profile: Option<FrameProfile>,

    /// User-configured baseline warp mesh size, captured at engine
    /// init. The MD1 per-pixel auto-upgrade (`md1_mesh_override`)
    /// densifies the mesh for MD1 presets; loading an MD2+ preset
    /// reverts to this baseline so the user's mesh-quality choice
    /// stays honoured on the common case. Manual `set_mesh_size`
    /// calls (e.g., GUI quality slider) update this baseline too.
    baseline_mesh: (u32, u32),

    /// MPRIS2 progress reader, when [`EngineConfig::progress_source`]
    /// requests it and the `mpris` feature is enabled. `None` means
    /// `progress` falls back to the local-window computation each
    /// frame (the historical behaviour).
    #[cfg(feature = "mpris")]
    mpris: Option<crate::mpris::MprisPoller>,

    /// Sprite (`MILK_IMG.INI`) manager: holds the parsed defs, the
    /// active sprite list, and runs per-frame equations against each
    /// active sprite's own evaluator. The result list is forwarded to
    /// the renderer's `update_sprites` each frame.
    sprites: crate::sprites::SpriteManager,

    /// Message (`MILK_MSG.INI`) overlay manager. Drives the text
    /// pipeline + the MPRIS auto-title path: when the MPRIS poller
    /// reports a new track title, the engine spawns a transient
    /// "Now playing — …" message.
    messages: crate::messages::MessageManager,

    /// Last MPRIS title observed — used to suppress duplicate
    /// `show_transient` spawns on idle polls that report the same
    /// metadata. `None` until the first non-empty title is seen.
    #[cfg(feature = "mpris")]
    mpris_last_title: Option<String>,
}

/// Engine configuration.
#[derive(Debug, Clone)]
pub struct EngineConfig {
    /// Render configuration
    pub render_config: RenderConfig,

    /// Audio sample rate
    pub sample_rate: f32,

    /// Enable per-frame equations
    pub enable_per_frame: bool,

    /// Enable per-pixel equations
    pub enable_per_pixel: bool,

    /// Duration of the crossfade between two presets. `0.0` disables
    /// transitions (instant cut). Default mirrors MD2's
    /// `f_transition_time = 2.7 s`.
    pub transition_duration_s: f32,

    /// Length of a preset's display window in seconds. Drives MD2's
    /// `progress` uniform: `progress = (time - preset_loaded_time)
    /// / preset_display_duration_s`, clamped to `[0, 1]`. Presets
    /// read `progress` for fade-ins, build-ups, and once-per-window
    /// effects. Default mirrors MD2's `nPresetDisplayLengthSeconds
    /// = 16`. Set `0.0` to disable (clamps `progress` to `0`).
    pub preset_display_duration_s: f32,

    /// Record per-phase wall-clock breakdown of every `update` call into
    /// [`MilkEngine::last_profile`]. Used by the bench tool. Off in the
    /// real GUI/CLI path.
    pub profile: bool,

    /// Waveform L/R top-vs-bottom split. When `true`, the static
    /// waveform pass renders the LEFT channel on the upper screen
    /// half and the RIGHT channel on the lower half (two dispatches
    /// with a `±0.25` `wave_y` offset). Default `false` (single
    /// mono trace). Surfaced at engine level rather than preset
    /// level — MD2 had a player-side option for this, not a preset
    /// variable.
    pub waveform_split_lr: bool,

    /// MD1-style per-pixel warp mode: when the loaded preset's version
    /// is `< 200` (MilkDrop 1), auto-upgrade the warp mesh to this
    /// resolution. MD1 presets routinely encode high-frequency warp
    /// formulas (`dx = sin(40*y)`, …) that MD2's mesh-based approach
    /// smooths over at coarse resolutions; densifying the mesh for the
    /// lifetime of the preset restores the "looks evaluated per pixel"
    /// feel without an actual full-resolution CPU eval (which would
    /// run EEL2 millions of times per frame).
    ///
    /// MD2+ presets revert to the user's baseline
    /// `RenderConfig::mesh_cols`/`mesh_rows` on the next load. `None`
    /// disables the override (every preset uses the baseline).
    ///
    /// Default `Some((96, 72))` — a sweet spot for a true per-pixel
    /// feel on classic MD1 presets without thrashing the warp
    /// executor's per-vertex evaluator. Cap is `WarpMesh::new`'s
    /// 192×96; lower if MD1 presets feel choppier than expected on
    /// underpowered hardware.
    pub md1_mesh_override: Option<(u32, u32)>,

    /// Source for MD2's `progress` uniform. Default
    /// [`ProgressSource::LocalWindow`] derives `progress` from
    /// `preset_display_duration_s` (the per-preset slot timer).
    /// [`ProgressSource::MprisAutoTrack`] asks the engine to query
    /// the freedesktop MPRIS2 bus on a background thread and use
    /// `Position / mpris:length` of the active player instead — so
    /// presets that fade with `progress` track the song rather than
    /// the slot. When the `mpris` cargo feature is off, the variant
    /// is still accepted but the engine silently falls back to
    /// `LocalWindow`.
    pub progress_source: ProgressSource,
}

/// Source for the MD2 `progress` uniform.
///
/// `LocalWindow` is the historical behaviour — `progress` ramps from
/// `0` at preset load to `1` after [`EngineConfig::preset_display_duration_s`]
/// seconds. `MprisAutoTrack` instead reads the active MPRIS2 player's
/// track position and clamps it to `[0, 1]`; presets that authoring
/// against `progress` (build-ups, fade-ins) sync to the song. When no
/// player is reachable or the metadata is incomplete, the variant
/// transparently falls back to `LocalWindow` per frame.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ProgressSource {
    /// Derive `progress` from `preset_display_duration_s`.
    LocalWindow,
    /// Read `progress` from the active MPRIS2 player's track position;
    /// fall back to `LocalWindow` when no player is reachable.
    MprisAutoTrack,
}

/// Quality preset for engine configuration.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum QualityPreset {
    /// Low quality - per-pixel disabled, optimized for performance
    Low,
    /// Medium quality - balanced settings (default)
    Medium,
    /// High quality - all features enabled
    High,
}

impl EngineConfig {
    /// Create configuration from a quality preset.
    pub fn from_preset(preset: QualityPreset) -> Self {
        match preset {
            QualityPreset::Low => Self {
                render_config: RenderConfig::default(),
                sample_rate: 44100.0,
                enable_per_frame: true,
                enable_per_pixel: false,
                transition_duration_s: 2.7,
                preset_display_duration_s: 16.0,
                profile: false,
                md1_mesh_override: Some((96, 72)),
                waveform_split_lr: false,
                progress_source: ProgressSource::LocalWindow,
            },
            QualityPreset::Medium => Self {
                render_config: RenderConfig::default(),
                sample_rate: 44100.0,
                enable_per_frame: true,
                enable_per_pixel: false,
                transition_duration_s: 2.7,
                preset_display_duration_s: 16.0,
                profile: false,
                md1_mesh_override: Some((96, 72)),
                waveform_split_lr: false,
                progress_source: ProgressSource::LocalWindow,
            },
            QualityPreset::High => Self {
                render_config: RenderConfig::default(),
                sample_rate: 44100.0,
                enable_per_frame: true,
                enable_per_pixel: true,
                transition_duration_s: 2.7,
                preset_display_duration_s: 16.0,
                profile: false,
                md1_mesh_override: Some((96, 72)),
                waveform_split_lr: false,
                progress_source: ProgressSource::LocalWindow,
            },
        }
    }
}

impl Default for EngineConfig {
    fn default() -> Self {
        Self::from_preset(QualityPreset::Medium)
    }
}

impl MilkEngine {
    /// Create a new engine.
    pub async fn new(config: EngineConfig) -> Result<Self> {
        let renderer = MilkRenderer::new(config.render_config.clone()).await?;
        Self::from_renderer(renderer, config)
    }

    /// Create an engine from an existing device and queue.
    /// This is useful when sharing a GPU context with a GUI.
    pub fn from_device(
        device: Arc<wgpu::Device>,
        queue: Arc<wgpu::Queue>,
        config: EngineConfig,
    ) -> Result<Self> {
        let gpu = GpuContext::from_device(device, queue, config.render_config.clone());
        let renderer = MilkRenderer::from_gpu_context(gpu)?;
        Self::from_renderer(renderer, config)
    }

    /// Create an engine from an existing renderer.
    fn from_renderer(mut renderer: MilkRenderer, config: EngineConfig) -> Result<Self> {
        let audio_analyzer = AudioAnalyzer::new(config.sample_rate);

        // Populate the user-texture pool from the XDG /
        // `~/Music/milkdrop/textures` candidate dirs. Missing dirs are
        // silently skipped; presets that reference unknown textures fall
        // back to the comp pipeline's 1×1 white. Engine consumers that
        // want a custom dir (`--textures /foo`) can call
        // `renderer.set_texture_pool` directly afterwards.
        {
            let device = renderer.gpu_device();
            let queue = renderer.gpu_queue();
            let dirs = onedrop_renderer::default_texture_dirs();
            let pool = onedrop_renderer::TexturePool::from_dirs(&device, &queue, &dirs);
            if !pool.is_empty() {
                log::info!("loaded {} user textures from XDG dirs", pool.len());
            }
            renderer.set_texture_pool(pool);
        }

        let fft = FFTAnalyzer::new_or_default(SPECTRUM_FFT_SIZE, config.sample_rate);
        let baseline_mesh = renderer.mesh_size();

        // MPRIS poller: only spawned when feature on AND config opts in.
        // A failure to reach the session bus (headless CI, sandboxed
        // runtime) collapses to `None` so the engine transparently
        // falls back to the local-window `progress`.
        #[cfg(feature = "mpris")]
        let mpris = match config.progress_source {
            ProgressSource::MprisAutoTrack => crate::mpris::MprisPoller::spawn(),
            ProgressSource::LocalWindow => None,
        };

        Ok(Self {
            renderer,
            current: PresetSlot::default(),
            fading_out: None,
            transition: None,
            audio_analyzer,
            beat_detector: BeatDetector::new(),
            config,
            fft,
            spectrum_bins: vec![0.0; SPECTRUM_FFT_SIZE / 2],
            last_profile: None,
            baseline_mesh,
            #[cfg(feature = "mpris")]
            mpris,
            sprites: crate::sprites::SpriteManager::new(),
            messages: crate::messages::MessageManager::new(),
            #[cfg(feature = "mpris")]
            mpris_last_title: None,
        })
    }

    /// Load a preset from file.
    pub fn load_preset<P: AsRef<Path>>(&mut self, path: P) -> Result<()> {
        const MAX_PRESET_SIZE: u64 = 10 * 1024 * 1024; // 10MB limit

        let path_ref = path.as_ref();
        log::info!("Loading preset: {}", path_ref.display());

        // Validate file size before loading
        let metadata = fs::metadata(path_ref).map_err(|e| {
            log::error!("Failed to read file metadata {}: {}", path_ref.display(), e);
            EngineError::PresetLoadFailed(format!("Cannot read file metadata: {}", e))
        })?;

        if metadata.len() > MAX_PRESET_SIZE {
            log::error!(
                "Preset file too large: {} bytes (max {})",
                metadata.len(),
                MAX_PRESET_SIZE
            );
            return Err(EngineError::PresetLoadFailed(format!(
                "File too large: {} bytes (max {} bytes)",
                metadata.len(),
                MAX_PRESET_SIZE
            )));
        }

        // Read file (UTF-8 lossy: presets in the wild routinely contain
        // legacy cp1252 bytes in track names / comments — fail-open).
        let bytes = fs::read(path_ref).map_err(|e| {
            log::error!("Failed to read preset file {}: {}", path_ref.display(), e);
            EngineError::PresetLoadFailed(format!("Cannot read file: {}", e))
        })?;
        let content = String::from_utf8_lossy(&bytes).into_owned();

        // Parse preset
        let preset = parse_preset(&content).map_err(|e| {
            log::error!("Failed to parse preset {}: {}", path_ref.display(), e);
            e
        })?;

        // Validate preset
        if preset.per_frame_equations.is_empty() && preset.per_pixel_equations.is_empty() {
            log::warn!(
                "Preset {} has no equations, using default parameters",
                path_ref.display()
            );
        }

        let result = self.load_preset_from_data(preset);

        // `MILK_IMG.INI` / `MILK_MSG.INI` sibling autoload — MD2
        // looked them up in the preset directory; we do the same so
        // user-authored sprite + message packs Just Work without an
        // explicit API call. Failures are silent (logged) since most
        // presets don't ship these files.
        if let Some(dir) = path_ref.parent() {
            self.autoload_overlay_inis(dir);
        }
        result
    }

    /// Look for `MILK_IMG.INI` and `MILK_MSG.INI` siblings of a preset
    /// file and load them into the sprite + message managers.
    /// Best-effort: missing / unparseable files log a warning and
    /// leave the previous load untouched.
    fn autoload_overlay_inis(&mut self, dir: &Path) {
        // Sprites.
        let img_path = dir.join("MILK_IMG.INI");
        if img_path.is_file() {
            match fs::read_to_string(&img_path) {
                Ok(content) => match onedrop_parser::parse_milk_img_ini(&content) {
                    Ok(defs) => {
                        log::info!(
                            "MILK_IMG.INI: loaded {} sprite defs from {}",
                            defs.len(),
                            img_path.display()
                        );
                        self.load_sprite_defs(defs, dir);
                    }
                    Err(e) => {
                        log::warn!("MILK_IMG.INI parse failed at {}: {}", img_path.display(), e)
                    }
                },
                Err(e) => log::warn!("MILK_IMG.INI read failed at {}: {}", img_path.display(), e),
            }
        }
        // Messages.
        let msg_path = dir.join("MILK_MSG.INI");
        if msg_path.is_file() {
            match fs::read_to_string(&msg_path) {
                Ok(content) => match onedrop_parser::parse_milk_msg_ini(&content) {
                    Ok(defs) => {
                        log::info!(
                            "MILK_MSG.INI: loaded {} message defs from {}",
                            defs.len(),
                            msg_path.display()
                        );
                        self.load_message_defs(defs);
                    }
                    Err(e) => {
                        log::warn!("MILK_MSG.INI parse failed at {}: {}", msg_path.display(), e)
                    }
                },
                Err(e) => log::warn!("MILK_MSG.INI read failed at {}: {}", msg_path.display(), e),
            }
        }
    }

    /// Load the default preset.
    /// This is useful as a fallback when no preset is available or loading fails.
    pub fn load_default_preset(&mut self) -> Result<()> {
        log::info!("Loading default preset");
        let preset = crate::default_preset::default_preset();
        self.load_preset_from_data(preset)
    }

    /// Load a preset from parsed data.
    ///
    /// When `config.transition_duration_s > 0` and a preset is already
    /// loaded, archives the current slot into `fading_out`, asks the
    /// renderer to allocate a secondary chain for it, and starts the
    /// transition timer. The next `update()` will tick both slots and
    /// drive the renderer's blend pass through the eased crossfade.
    pub fn load_preset_from_data(&mut self, preset: MilkPreset) -> Result<()> {
        log::info!("Loading preset version {}", preset.version);

        // Start a transition when there's a previous preset and the
        // configured duration is non-zero. Drop any pending transition
        // (rare: load called mid-fade) — the new outgoing preset is
        // simply the current one.
        let start_transition =
            self.config.transition_duration_s > 0.0 && self.current.preset.is_some();
        if start_transition {
            self.renderer.start_transition()?;
            let outgoing = std::mem::take(&mut self.current);
            // Carry the global frame counter + time across preset changes
            // so external observers (HUD, tests, user shaders sampling
            // `time` / `frame`) see a continuous monotonic stream. Each
            // slot still owns the rest of its `RenderState` (motion,
            // wave, q snapshot, …) independently — only the global
            // counters bleed across.
            self.current = PresetSlot::default();
            self.current.state.frame = outgoing.state.frame;
            self.current.state.time = outgoing.state.time;
            // `progress` resets each preset load; anchor at the
            // current global time so `progress = (now - anchor) /
            // duration` starts at 0 for the freshly-loaded preset.
            self.current.preset_loaded_time = outgoing.state.time;
            self.fading_out = Some(outgoing);
            self.transition = Some(TransitionState::new(self.config.transition_duration_s));
            self.renderer.set_transition_progress(0.0);
        } else {
            // Cut: drop any stale fading_out from a previous in-flight
            // transition and reset the renderer's secondary chain.
            self.fading_out = None;
            self.transition = None;
            self.renderer.clear_secondary_chain();
            // Anchor `progress` to the current global time so the new
            // preset starts at `progress = 0`.
            self.current.preset_loaded_time = self.current.state.time;
        }

        // MD1-style per-pixel warp: densify the mesh for MilkDrop 1
        // presets (version < 200) so high-frequency warp formulas
        // don't get smoothed out by mesh interpolation. MD2+ presets
        // revert to the user's baseline mesh size so the user's
        // explicit quality preference is honoured on the common path.
        match self.config.md1_mesh_override {
            Some((cols, rows)) if preset.version < 200 => {
                let cur = self.renderer.mesh_size();
                if cur != (cols, rows) {
                    log::info!(
                        "MD1 preset detected (version {}); upgrading warp mesh to {}×{}",
                        preset.version,
                        cols,
                        rows
                    );
                    self.renderer.set_mesh_size(cols, rows);
                }
            }
            _ => {
                let baseline = self.baseline_mesh;
                if self.renderer.mesh_size() != baseline {
                    self.renderer.set_mesh_size(baseline.0, baseline.1);
                }
            }
        }

        // Initialize evaluator context with preset parameters
        self.init_evaluator_from_preset(&preset);

        // Pre-compile per-vertex equations once; subsequent frames just
        // execute the compiled `Node`s against a scratch context.
        self.current
            .warp_executor
            .set_equations(&mut self.current.evaluator, &preset.per_pixel_equations);

        // Translate + compile the preset's user comp shader and either
        // swap it into the comp pass or fall back to the gamma-only
        // default. Compile failures are non-fatal: the renderer keeps
        // rendering, just without the user-authored composite. This
        // matches MilkDrop's classic behaviour where presets with broken
        // shaders are still navigable.
        //
        // The `preset_id` argument seeds `sampler_rand0X` deterministically.
        // No filename is available here (`load_preset_from_data` accepts
        // pre-parsed data) so we derive it from the comp shader content —
        // identical comp_shaders → identical rand selection, distinct
        // ones diverge. Real `load_preset(path)` callers get the filename
        // path threaded into this via the `current_preset` it stores.
        let preset_id = preset_id_for(&preset);
        match self
            .renderer
            .set_user_comp_shader_for_preset(preset.comp_shader.as_deref(), &preset_id)
        {
            Ok(true) => {
                if preset.comp_shader.is_some() {
                    log::info!("user comp shader compiled and active");
                }
            }
            Ok(false) => {
                log::info!("user comp shader fell back to default — see prior warning");
            }
            Err(e) => return Err(EngineError::from(e)),
        }

        // Same path for the warp shader: if the preset ships one,
        // translate + wrap + validate, then swap the warp pass over to
        // the user pipeline. Failure falls back to the default
        // hand-written `warp.wgsl` (decay + flags), so the render loop
        // stays alive on any preset.
        match self
            .renderer
            .set_user_warp_shader_for_preset(preset.warp_shader.as_deref(), &preset_id)
        {
            Ok(true) => {
                if preset.warp_shader.is_some() {
                    log::info!("user warp shader compiled and active");
                }
            }
            Ok(false) => {
                log::info!("user warp shader fell back to default — see prior warning");
            }
            Err(e) => return Err(EngineError::from(e)),
        }

        // Compile each enabled wavecode_N block's init/per_frame/per_point
        // equations once. Eval runs cached `Node`s every frame, skipping
        // the regex-based preprocess.
        // Failures inside a single phase are non-fatal: the equation is
        // dropped from the compiled list (logged) and the wave keeps
        // running with whatever did compile. This matches MD2's
        // permissive load behaviour.
        self.current.compiled_waves.clear();
        self.current.waves_need_init.clear();
        for w in &preset.waves {
            // init / per_frame go through CompiledBlock so they pick up
            // the bytecode VM transparently when their nodes lower
            // cleanly (most do — see CompiledBlock::from_nodes).
            //
            // Each `from_nodes` call needs `&mut evaluator.context` to
            // intern cold-var names into the slab; structure the calls
            // as two steps (compile_phase, then from_nodes) so the two
            // mutable borrows of `evaluator` happen sequentially rather
            // than nested.
            let init_nodes =
                Self::compile_phase(&mut self.current.evaluator, &w.per_frame_init_equations);
            let init = onedrop_eval::CompiledBlock::from_nodes(
                init_nodes,
                self.current.evaluator.context_mut(),
            );
            let pf_nodes = Self::compile_phase(&mut self.current.evaluator, &w.per_frame_equations);
            let per_frame = onedrop_eval::CompiledBlock::from_nodes(
                pf_nodes,
                self.current.evaluator.context_mut(),
            );
            let per_point =
                Self::compile_phase(&mut self.current.evaluator, &w.per_point_equations);
            // Cache the parallelism verdict for the per-point block. The
            // analysis is a single AST walk — running it once at preset
            // load amortises it across thousands of frames.
            let per_point_parallelism = onedrop_eval::analyse_per_point(&per_point);
            // Try to lower per_point into the stack-VM bytecode. Any
            // operator/function the VM doesn't support (no opcode for
            // it) returns Err and we fall back to evalexpr Nodes for
            // that wave. Logged at debug — bench-only, not actionable.
            // Kept as a separate Option (rather than CompiledBlock) so
            // the parallel-samples branch in `compute_one_wave` can
            // distinguish bytecode vs Nodes per worker.
            let per_point_bytecode = match onedrop_eval::CompiledBytecode::try_compile(
                &per_point,
                self.current.evaluator.context_mut(),
            ) {
                Ok(bc) => Some(bc),
                Err(e) => {
                    log::debug!(
                        "wave[{}] per_point stays on evalexpr (reason: {})",
                        w.index,
                        e
                    );
                    None
                }
            };
            self.current.compiled_waves.push(CompiledWave {
                init,
                per_frame,
                per_point,
                per_point_parallelism,
                per_point_bytecode,
            });
            self.current.waves_need_init.push(true);
        }

        // Same compile pattern for shapecode_N. Shapes have no per_point
        // block (the per_frame block runs once per instance), so only two
        // phases.
        self.current.compiled_shapes.clear();
        self.current.shapes_need_init.clear();
        for s in &preset.shapes {
            let init_nodes =
                Self::compile_phase(&mut self.current.evaluator, &s.per_frame_init_equations);
            let init = onedrop_eval::CompiledBlock::from_nodes(
                init_nodes,
                self.current.evaluator.context_mut(),
            );
            let pf_nodes = Self::compile_phase(&mut self.current.evaluator, &s.per_frame_equations);
            let per_frame = onedrop_eval::CompiledBlock::from_nodes(
                pf_nodes,
                self.current.evaluator.context_mut(),
            );
            self.current
                .compiled_shapes
                .push(CompiledShape { init, per_frame });
            self.current.shapes_need_init.push(true);
        }

        // Pre-compile the main-preset `per_frame_init` + `per_frame`
        // blocks. Until this landed both lists were re-parsed every
        // frame through `MilkEvaluator::eval_per_frame(&[String])`,
        // even though the source strings never change between frames.
        // CompiledBlock now lifts them into bytecode (with evalexpr
        // fallback) so the per-frame eval phase shares the same fast
        // path as wave/shape per_frame.
        let pf_init_nodes = Self::compile_phase(
            &mut self.current.evaluator,
            &preset.per_frame_init_equations,
        );
        self.current.compiled_per_frame_init = onedrop_eval::CompiledBlock::from_nodes(
            pf_init_nodes,
            self.current.evaluator.context_mut(),
        );
        let pf_nodes =
            Self::compile_phase(&mut self.current.evaluator, &preset.per_frame_equations);
        self.current.compiled_per_frame =
            onedrop_eval::CompiledBlock::from_nodes(pf_nodes, self.current.evaluator.context_mut());

        // `per_frame_init` runs once at preset load — same semantics as
        // the per-wave/per-shape init blocks.
        let init_block = std::mem::replace(
            &mut self.current.compiled_per_frame_init,
            onedrop_eval::CompiledBlock::empty(),
        );
        run_block_with_logger(&mut self.current.evaluator, &init_block, |idx, e| {
            log::warn!("preset per_frame_init equation[{}] failed: {}", idx, e);
        });
        self.current.compiled_per_frame_init = init_block;

        self.current.preset = Some(preset);

        Ok(())
    }

    /// Compile a single equation-phase batch, logging individual
    /// failures and returning the surviving Nodes. Public-by-convention
    /// for testability inside the module.
    fn compile_phase(evaluator: &mut MilkEvaluator, equations: &[String]) -> Vec<Node> {
        let mut nodes = Vec::with_capacity(equations.len());
        for eq in equations {
            match evaluator.compile(eq) {
                Ok(n) => nodes.push(n),
                Err(e) => log::warn!("wavecode equation compile failed (`{}`): {}", eq, e),
            }
        }
        nodes
    }

    /// Initialize evaluator context from preset parameters.
    fn init_evaluator_from_preset(&mut self, preset: &MilkPreset) {
        let ctx = self.current.evaluator.context_mut();
        let params = &preset.parameters;

        // Set motion parameters
        ctx.set_var("zoom", params.zoom as f64);
        ctx.set_var("zoomexp", params.zoomexp() as f64);
        ctx.set_var("rot", params.rot as f64);
        ctx.set_var("warp", params.warp as f64);
        ctx.set_var("cx", params.cx as f64);
        ctx.set_var("cy", params.cy as f64);
        ctx.set_var("dx", params.dx as f64);
        ctx.set_var("dy", params.dy as f64);
        ctx.set_var("sx", params.sx as f64);
        ctx.set_var("sy", params.sy as f64);

        // Set wave parameters
        ctx.set_var("wave_r", params.wave_r as f64);
        ctx.set_var("wave_g", params.wave_g as f64);
        ctx.set_var("wave_b", params.wave_b as f64);
        ctx.set_var("wave_a", params.wave_a() as f64);
        ctx.set_var("wave_x", params.wave_x as f64);
        ctx.set_var("wave_y", params.wave_y as f64);
        ctx.set_var("wave_mode", params.wave_mode() as f64);

        // Full MD2 wave cluster threaded through the evaluator so
        // per-frame eqs can flip any of these on the fly.
        ctx.set_var("wave_scale", params.f_wave_scale as f64);
        ctx.set_var("wave_param", params.f_wave_param as f64);
        ctx.set_var("wave_smoothing", params.f_wave_smoothing as f64);
        ctx.set_var("wave_thick", if params.b_wave_thick { 1.0 } else { 0.0 });
        ctx.set_var("wave_dots", if params.b_wave_dots { 1.0 } else { 0.0 });
        ctx.set_var(
            "additivewave",
            if params.b_additive_waves { 1.0 } else { 0.0 },
        );
        ctx.set_var(
            "wave_brighten",
            if params.b_maximize_wave_color {
                1.0
            } else {
                0.0
            },
        );
        ctx.set_var(
            "modwavealphabyvolume",
            if params.b_mod_wave_alpha_by_volume {
                1.0
            } else {
                0.0
            },
        );
        ctx.set_var("modwavealphastart", params.f_mod_wave_alpha_start as f64);
        ctx.set_var("modwavealphaend", params.f_mod_wave_alpha_end as f64);

        // Set other parameters
        ctx.set_var("decay", params.decay() as f64);
        ctx.set_var("gamma", params.gamma() as f64);
        ctx.set_var("echo_zoom", params.echo_zoom() as f64);
        ctx.set_var("echo_alpha", params.echo_alpha() as f64);
        // Seed `echo_orient` so presets shipping `nVideoEchoOrientation`
        // without a per-frame eq still flip the echo sample. Two aliases are
        // seeded for symmetry with the read path in
        // `update_render_state_from_evaluator`.
        ctx.set_var(
            "echo_orient",
            params.n_video_echo_orientation.clamp(0, 3) as f64,
        );
        ctx.set_var(
            "video_echo_orientation",
            params.n_video_echo_orientation.clamp(0, 3) as f64,
        );
        ctx.set_var(
            "darken_center",
            if params.darken_center() { 1.0 } else { 0.0 },
        );
        ctx.set_var(
            "red_blue_stereo",
            if params.b_red_blue_stereo { 1.0 } else { 0.0 },
        );
        ctx.set_var("wrap", if params.wrap() { 1.0 } else { 0.0 });
        ctx.set_var("invert", if params.invert() { 1.0 } else { 0.0 });
        ctx.set_var("brighten", if params.brighten() { 1.0 } else { 0.0 });
        ctx.set_var("darken", if params.darken() { 1.0 } else { 0.0 });
        ctx.set_var("solarize", if params.solarize() { 1.0 } else { 0.0 });

        // Outer + inner border + motion-vector grid. Seed the evaluator
        // with the preset's scalars so per-frame eqs can animate them
        // (e.g. flashing `ob_a` on a beat). Motion-vector grid size falls
        // back to the MD2 default of 12×9 when the preset omits
        // `nMotionVectorsX/Y` (they parse as 0.0).
        ctx.set_var("ob_size", params.ob_size as f64);
        ctx.set_var("ob_r", params.ob_r as f64);
        ctx.set_var("ob_g", params.ob_g as f64);
        ctx.set_var("ob_b", params.ob_b as f64);
        ctx.set_var("ob_a", params.ob_a as f64);
        ctx.set_var("ib_size", params.ib_size as f64);
        ctx.set_var("ib_r", params.ib_r as f64);
        ctx.set_var("ib_g", params.ib_g as f64);
        ctx.set_var("ib_b", params.ib_b as f64);
        ctx.set_var("ib_a", params.ib_a as f64);
        let nmv_x = if params.n_motion_vectors_x > 0.0 {
            params.n_motion_vectors_x
        } else {
            12.0
        };
        let nmv_y = if params.n_motion_vectors_y > 0.0 {
            params.n_motion_vectors_y
        } else {
            9.0
        };
        ctx.set_var("nMotionVectorsX", nmv_x as f64);
        ctx.set_var("nMotionVectorsY", nmv_y as f64);
        ctx.set_var("mv_dx", params.mv_dx as f64);
        ctx.set_var("mv_dy", params.mv_dy as f64);
        ctx.set_var("mv_l", params.mv_l as f64);
        ctx.set_var("mv_r", params.mv_r as f64);
        ctx.set_var("mv_g", params.mv_g as f64);
        ctx.set_var("mv_b", params.mv_b as f64);
        ctx.set_var("mv_a", params.mv_a as f64);
    }

    /// Update engine with mono audio + render a frame. Convenience
    /// wrapper around [`Self::update_stereo`] that feeds the same buffer
    /// for both channels — handy for callers that only have a downmixed
    /// stream (CLI render path, test fixtures, headless smoke tests).
    /// Custom waves' `value2` will mirror `value1`; real stereo content
    /// requires [`Self::update_stereo`].
    ///
    /// Returns `Some(PresetChange)` if beat detection triggered a preset
    /// change.
    pub fn update(
        &mut self,
        audio_samples: &[f32],
        delta_time: f32,
    ) -> Result<Option<PresetChange>> {
        self.update_stereo(audio_samples, audio_samples, delta_time)
    }

    /// Update engine with split L/R audio + render a frame. The two
    /// buffers must be the same length; MD2 custom waves'
    /// `value1` reads from `left`, `value2` from `right`. Audio
    /// analysis (band levels, beat detection, FFT spectrum) runs on a
    /// downmix of the two channels — the perceptual loudness those
    /// metrics report is the listener's, not one channel's.
    ///
    /// `delta_time` is in seconds; the engine multiplies it into every
    /// per-frame time step.
    pub fn update_stereo(
        &mut self,
        left: &[f32],
        right: &[f32],
        delta_time: f32,
    ) -> Result<Option<PresetChange>> {
        // Downmix for the engine-wide audio analyzers (bass/mid/treb +
        // beat detector + FFT spectrum). Perceptual loudness lives at
        // the listener's ear, not in one channel — and historically MD2
        // band levels were computed on the mixed input anyway. Sharing
        // a single buffer alloc per frame keeps the cost negligible.
        // When `left.as_ptr() == right.as_ptr()` (the mono case from
        // `update()` above), `Cow::Borrowed` lets us skip the alloc.
        let downmix: std::borrow::Cow<'_, [f32]> = if std::ptr::eq(left, right) {
            std::borrow::Cow::Borrowed(left)
        } else {
            let n = left.len().min(right.len());
            std::borrow::Cow::Owned((0..n).map(|i| 0.5 * (left[i] + right[i])).collect())
        };
        let audio_samples: &[f32] = &downmix;
        let profile_enabled = self.config.profile;
        let frame_start = profile_enabled.then(Instant::now);
        let mut profile = FrameProfile::default();
        // Helper closures: capture `&mut profile` and `profile_enabled`.
        // Returning a Duration is cheap; `Instant::elapsed` is ~20 ns.
        macro_rules! phase {
            ($field:ident, $body:expr) => {{
                if profile_enabled {
                    let t = Instant::now();
                    let r = $body;
                    profile.$field += t.elapsed();
                    r
                } else {
                    $body
                }
            }};
        }

        // Analyze audio + run beat detection — both are engine-global and
        // feed every active slot.
        let audio_levels = phase!(audio_analyze, self.audio_analyzer.analyze(audio_samples));
        let preset_change = self.beat_detector.should_change_preset(
            audio_levels.bass,
            audio_levels.mid,
            audio_levels.treb,
        );

        // Refresh the FFT spectrum once per frame; shared between slots
        // (both audio bins and analyzer are engine-wide).
        phase!(spectrum_fft, self.update_spectrum(audio_samples));

        // --- Per-slot evaluation ---
        //
        // First tick the primary (current) slot. Then, if a transition is
        // in flight, tick the outgoing (fading_out) slot identically — same
        // audio, same delta — so both presets get a coherent per-frame
        // step. The two slots own independent evaluator contexts and
        // RenderStates so they don't trample each other.

        // Read the MPRIS snapshot once per frame and feed the same value
        // to both slots so `progress` stays coherent across a transition.
        // `None` means "no usable track position" → fall back to the
        // local-window computation inside `tick_slot_evaluator`.
        let track_progress = self.track_progress_override();

        phase!(
            per_frame_eval,
            tick_slot_evaluator(
                &mut self.current,
                audio_levels,
                delta_time,
                self.config.enable_per_frame,
                self.config.preset_display_duration_s,
                track_progress,
            )
        );

        if let Some(slot) = self.fading_out.as_mut() {
            phase!(
                per_frame_eval,
                tick_slot_evaluator(
                    slot,
                    audio_levels,
                    delta_time,
                    self.config.enable_per_frame,
                    self.config.preset_display_duration_s,
                    track_progress,
                )
            );
        }

        // Smart boolean interpolation of motion params + flags between
        // the two slots, applied *before* the state sync so both chains'
        // `state.motion` and downstream warp inputs see the morphed
        // values. Split-borrow the disjoint fields so we can hold mutable
        // refs to both slots and an immutable ref to the timer.
        {
            let fading = &mut self.fading_out;
            let current = &mut self.current;
            let transition = &self.transition;
            if let (Some(slot), Some(t)) = (fading.as_mut(), transition.as_ref()) {
                morph::apply_smart_boolean_interpolation(slot, current, t.linear());
            }
        }

        phase!(state_sync, state_sync::sync_render_state(&mut self.current));
        if let Some(slot) = self.fading_out.as_mut() {
            phase!(state_sync, state_sync::sync_render_state(slot));
        }

        // `state.wave.split_lr` is a player-side toggle, not a preset
        // variable — `sync_render_state` defaults it to `false`; we
        // overlay the engine config here so both slots see it during
        // a transition.
        self.current.state.wave.split_lr = self.config.waveform_split_lr;
        if let Some(slot) = self.fading_out.as_mut() {
            slot.state.wave.split_lr = self.config.waveform_split_lr;
        }

        // --- Primary chain: per-vertex warp + waveform + custom waves/shapes ---
        let mesh = self.renderer.warp_mesh();
        let primary_warp = phase!(
            warp_compute,
            self.current.warp_executor.compute(
                mesh,
                &self.current.evaluator,
                self.current.state.time,
            )
        );
        self.renderer.update_warp_vertices(&primary_warp);
        self.renderer.update_state(self.current.state);
        let vol = (audio_levels.bass + audio_levels.mid + audio_levels.treb) / 3.0;
        phase!(
            waveform_samples,
            self.renderer.update_waveform_samples_lr(left, right, vol)
        );

        let (waves_v, waves_b) = phase!(
            custom_waves,
            wave_phase::compute_custom_waves(&mut self.current, left, right, &self.spectrum_bins,)
        );
        self.renderer.update_custom_waves(&waves_v, &waves_b);

        let (shapes_i, shapes_b) = phase!(
            custom_shapes,
            shape_phase::compute_custom_shapes(&mut self.current)
        );
        self.renderer.update_custom_shapes(&shapes_i, &shapes_b);

        // --- Sprites (§5): tick each active sprite against the current
        // q snapshot and forward the resulting frames to the renderer.
        // Sprites are a global overlay, not per-preset — only the
        // primary slot's q values feed the per-frame eval (matches
        // MD2's behaviour: `MILK_IMG.INI` lives outside the preset).
        let q_snap = self.current.state.q_snapshot;
        let sprite_instances = self.sprites.tick(self.current.state.time, &q_snap);
        let sprite_frames: Vec<onedrop_renderer::SpriteFrame> = sprite_instances
            .iter()
            .map(|s| onedrop_renderer::SpriteFrame {
                texture_index: s.texture_index,
                x: s.x,
                y: s.y,
                sx: s.sx,
                sy: s.sy,
                rot: s.rot,
                rgba: s.rgba,
                blend: match s.blend {
                    crate::sprites::SpriteBlendMode::Alpha => {
                        onedrop_renderer::SpriteBlendKind::Alpha
                    }
                    crate::sprites::SpriteBlendMode::Additive => {
                        onedrop_renderer::SpriteBlendKind::Additive
                    }
                },
                burn: s.burn,
            })
            .collect();
        self.renderer.update_sprites(&sprite_frames);

        // --- MPRIS auto-title (§6): when the active MPRIS player
        // reports a new title, spawn a transient "now playing"
        // message. Cheap — runs only when the feature is built and
        // the snapshot's title actually changed.
        #[cfg(feature = "mpris")]
        if let Some(poller) = self.mpris.as_ref() {
            let snap = poller.snapshot();
            if let Some(title) = snap.title.as_ref() {
                let changed = self
                    .mpris_last_title
                    .as_deref()
                    .map(|t| t != title.as_str())
                    .unwrap_or(true);
                if changed && !title.is_empty() {
                    self.messages
                        .show_transient(format!("♪ {}", title), self.current.state.time);
                    self.mpris_last_title = Some(title.clone());
                }
            }
        }

        // --- Messages (§6): tick fade timing + forward render
        // instances to the renderer's text pipeline.
        let message_instances = self.messages.tick(self.current.state.time);
        let text_frames: Vec<onedrop_renderer::TextFrame> = message_instances
            .iter()
            .map(|m| onedrop_renderer::TextFrame {
                text: m.text.clone(),
                font: m.font,
                size_px: m.size_px,
                x: m.x,
                y: m.y,
                rgba: m.rgba,
            })
            .collect();
        self.renderer.update_text_frames(&text_frames);

        // --- Secondary chain (if transitioning): same flow, different slot ---
        if let Some(slot) = self.fading_out.as_mut() {
            let sec_warp = slot.warp_executor.compute(
                self.renderer.warp_mesh(),
                &slot.evaluator,
                slot.state.time,
            );
            self.renderer.update_secondary_warp_vertices(&sec_warp);
            self.renderer.update_secondary_state(Some(slot.state));
            self.renderer
                .update_secondary_waveform_samples_lr(left, right, vol, slot.state.wave);

            let (waves_v, waves_b) =
                wave_phase::compute_custom_waves(slot, left, right, &self.spectrum_bins);
            self.renderer
                .update_secondary_custom_waves(&waves_v, &waves_b);

            let (shapes_i, shapes_b) = shape_phase::compute_custom_shapes(slot);
            self.renderer
                .update_secondary_custom_shapes(&shapes_i, &shapes_b);
        } else {
            self.renderer.update_secondary_state(None);
        }

        // --- Transition timer ---
        if let Some(t) = self.transition.as_mut() {
            t.tick(delta_time);
            self.renderer.set_transition_progress(t.eased());
            if t.is_complete() {
                self.fading_out = None;
                self.transition = None;
                self.renderer.clear_secondary_chain();
            }
        }

        // Render frame
        phase!(gpu_render, self.renderer.render()?);

        // Bump frame counters AFTER the render so `comp_uniforms` saw the
        // pre-tick frame (matches pre-V.3 ordering). Both slots advance in
        // lock-step during a transition.
        self.current.state.frame += 1;
        if let Some(slot) = self.fading_out.as_mut() {
            slot.state.frame += 1;
        }

        if let Some(t) = frame_start {
            profile.total = t.elapsed();
            self.last_profile = Some(profile);
        }

        Ok(preset_change)
    }

    /// Per-phase wall-clock breakdown of the most recent `update` call.
    /// Returns `None` unless `EngineConfig::profile` was set. Cleared on
    /// engine reset.
    pub fn last_profile(&self) -> Option<&FrameProfile> {
        self.last_profile.as_ref()
    }

    /// Return the current transition's eased progress in `[0, 1]`, or
    /// `None` when no transition is in flight. Useful for HUD overlays
    /// and tests.
    pub fn transition_progress(&self) -> Option<f32> {
        self.transition.as_ref().map(|t| t.eased())
    }

    /// `true` while a preset transition is animating. Equivalent to
    /// `transition_progress().is_some()`.
    pub fn is_transitioning(&self) -> bool {
        self.transition.is_some()
    }

    /// Refresh the FFT magnitude spectrum from the current audio frame.
    /// Used by `b_spectrum = 1` `wavecode_N` blocks to populate
    /// `value1`/`value2`. Always runs (even with no preset loaded) so
    /// the buffer stays warm across preset hops.
    fn update_spectrum(&mut self, audio_samples: &[f32]) {
        let bins = self.fft.analyze(audio_samples);
        let n = bins.len().min(self.spectrum_bins.len());
        self.spectrum_bins[..n].copy_from_slice(&bins[..n]);
        for slot in self.spectrum_bins.iter_mut().skip(n) {
            *slot = 0.0;
        }
    }

    /// Get the current render texture.
    pub fn render_texture(&self) -> &wgpu::Texture {
        self.renderer.render_texture()
    }

    /// Get current state.
    pub fn state(&self) -> &RenderState {
        &self.current.state
    }

    /// Get current preset.
    pub fn current_preset(&self) -> Option<&MilkPreset> {
        self.current.preset.as_ref()
    }

    /// Snapshot of `q1..q32` after the most recent `update`.
    ///
    /// Returned as `f32` so a future GPU pipeline can copy it directly into a
    /// `q: array<vec4<f32>, 8>` uniform (MilkDrop 2's standard q-channel
    /// layout). The CPU-side bridge — per-frame eqs write `q1..q32`,
    /// per-vertex eqs read them, identical state restored across vertices —
    /// is already in place via `WarpExecutor`; this getter is the GPU-side
    /// hand-off point for upcoming comp/warp user shaders (sprint B).
    pub fn q_snapshot(&self) -> [f32; 32] {
        let ctx = self.current.evaluator.context();
        let mut out = [0.0f32; 32];
        for (i, slot) in out.iter_mut().enumerate() {
            // q1..q32 live in MilkContext's array-backed q_vars; index
            // straight into the slot rather than rebuilding the
            // `"qN"` name string and going through the trait `get`
            // path.
            *slot = ctx.q_get_idx(i) as f32;
        }
        out
    }

    /// Get the beat detector.
    pub fn beat_detector(&self) -> &BeatDetector {
        &self.beat_detector
    }

    /// Get the beat detector mutably.
    pub fn beat_detector_mut(&mut self) -> &mut BeatDetector {
        &mut self.beat_detector
    }

    /// Set beat detection mode.
    pub fn set_beat_detection_mode(&mut self, mode: BeatDetectionMode) {
        self.beat_detector.set_mode(mode);
    }

    /// Toggle beat detection to next mode.
    pub fn next_beat_detection_mode(&mut self) {
        self.beat_detector.next_mode();
    }

    /// Enable beat detection.
    pub fn enable_beat_detection(&mut self) {
        self.beat_detector.enable();
    }

    /// Disable beat detection.
    pub fn disable_beat_detection(&mut self) {
        self.beat_detector.disable();
    }

    /// Load a set of parsed `MILK_IMG.INI` sprite definitions and pre-
    /// resolve their image files against `dir`. Missing files fall
    /// back to a 1×1 transparent texture inside the renderer's sprite
    /// pool — the engine's `texture_index` mapping stays dense.
    pub fn load_sprite_defs(
        &mut self,
        defs: Vec<onedrop_parser::SpriteDef>,
        dir: &std::path::Path,
    ) {
        let imgs: Vec<String> = defs.iter().map(|d| d.img.clone()).collect();
        self.renderer.load_sprite_defs(dir, &imgs);
        self.sprites.load_defs(defs);
    }

    /// Spawn the sprite at INI slot `slot` (1-based, matching the
    /// `[img01]` section header). Returns `false` if no def is
    /// loaded for that slot. Multiple spawns of the same slot stack
    /// — that matches MD2 + lets `K`-hammering build up effects.
    pub fn spawn_sprite_slot(&mut self, slot: u32) -> bool {
        self.sprites.spawn_slot(slot)
    }

    /// Cycle to the next sprite slot (`K` keybind). Returns the slot
    /// that was spawned (or `None` if no sprites are loaded).
    pub fn cycle_next_sprite(&mut self) -> Option<u32> {
        self.sprites.cycle_next()
    }

    /// Spawn a random sprite (`Shift+K` keybind). The caller supplies
    /// the RNG seed (typically `state.frame as u64 ^ time bits`) so
    /// tests stay deterministic.
    pub fn spawn_random_sprite(&mut self, seed: u64) -> Option<u32> {
        self.sprites.spawn_random(seed)
    }

    /// Drop every active sprite (`Ctrl+T` keybind).
    pub fn clear_sprites(&mut self) {
        self.sprites.clear();
    }

    /// Remove the most recently spawned sprite (`Delete` keybind).
    /// Returns `true` when something was popped — the GUI suppresses
    /// the keystroke on an empty list.
    pub fn pop_most_recent_sprite(&mut self) -> bool {
        self.sprites.pop_most_recent()
    }

    /// Number of loaded sprite definitions (size of the texture pool).
    pub fn sprite_def_count(&self) -> usize {
        self.sprites.def_count()
    }

    /// Number of sprites being drawn this frame.
    pub fn sprite_active_count(&self) -> usize {
        self.sprites.active_count()
    }

    /// Load a set of parsed `MILK_MSG.INI` message definitions.
    /// Replaces the previous load.
    pub fn load_message_defs(&mut self, defs: Vec<onedrop_parser::MessageDef>) {
        self.messages.load_defs(defs);
    }

    /// Spawn the message at INI slot `slot`. Returns `false` if no
    /// def matches that slot.
    pub fn spawn_message_slot(&mut self, slot: u32) -> bool {
        self.messages.spawn_slot(slot, self.current.state.time)
    }

    /// Cycle through the loaded message slots (`T` keybind). Returns
    /// the slot that was spawned, or `None` if no messages are
    /// loaded.
    pub fn cycle_next_message(&mut self) -> Option<u32> {
        self.messages.cycle_next(self.current.state.time)
    }

    /// Drop every active message (`Ctrl+Y` keybind).
    pub fn clear_messages(&mut self) {
        self.messages.clear();
    }

    /// Show an ad-hoc transient message. Used by the MPRIS-driven
    /// auto-title path; surfaced publicly so the GUI can post its
    /// own transient toasts ("preset loaded", "audio source: …", …).
    pub fn show_transient_message(&mut self, text: impl Into<String>) {
        self.messages.show_transient(text, self.current.state.time);
    }

    pub fn message_def_count(&self) -> usize {
        self.messages.def_count()
    }

    pub fn message_active_count(&self) -> usize {
        self.messages.active_count()
    }

    /// Get a reference to the renderer.
    pub fn renderer(&self) -> &MilkRenderer {
        &self.renderer
    }

    /// Get a mutable reference to the renderer.
    pub fn renderer_mut(&mut self) -> &mut MilkRenderer {
        &mut self.renderer
    }

    /// Borrow the engine config — used by the GUI's Options panel to
    /// reflect current values in widgets at startup.
    pub fn config(&self) -> &EngineConfig {
        &self.config
    }

    /// Mutate hot-toggleable config fields (`enable_per_frame`,
    /// `transition_duration_s`, `profile`). The GUI's Options panel
    /// calls this when the user moves a widget. Fields that aren't
    /// safely hot-swappable (render_config, sample_rate) should not
    /// be poked here — change them via dedicated APIs that handle
    /// the side effects (pipeline rebuild, audio stream restart).
    pub fn config_mut(&mut self) -> &mut EngineConfig {
        &mut self.config
    }

    /// Reset engine state.
    pub fn reset(&mut self) {
        self.current.state = RenderState::default();
        self.current.evaluator.reset();
        self.audio_analyzer.reset();
    }

    /// Resize the renderer.
    pub fn resize(&mut self, width: u32, height: u32) {
        self.renderer.resize(width, height);
    }

    /// Resolve the MD2 `progress` override for the current frame.
    ///
    /// Returns `Some(p)` when [`EngineConfig::progress_source`] is
    /// [`ProgressSource::MprisAutoTrack`], the `mpris` feature is
    /// enabled, *and* an MPRIS player is reachable with a non-zero
    /// `mpris:length`. Returns `None` otherwise so the slot tick
    /// falls back to the local-window computation.
    fn track_progress_override(&self) -> Option<f32> {
        #[cfg(feature = "mpris")]
        {
            if matches!(self.config.progress_source, ProgressSource::MprisAutoTrack) {
                return self.mpris.as_ref().and_then(|m| m.snapshot().progress);
            }
        }
        None
    }

    /// Current MPRIS snapshot, when the `mpris` feature is enabled and
    /// a poller is active. Exposed so a HUD/overlay can render the
    /// track title without opening its own D-Bus connection.
    #[cfg(feature = "mpris")]
    pub fn mpris_snapshot(&self) -> Option<crate::mpris::MprisSnapshot> {
        self.mpris.as_ref().map(|m| m.snapshot())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// `tick_slot_evaluator` must use the override verbatim (clamped)
    /// when one is supplied — the local-window timer is ignored, so a
    /// freshly-loaded preset whose anchor would otherwise give
    /// `progress ≈ 0` instead reports the MPRIS-fed mid-track value.
    #[test]
    fn track_progress_override_replaces_local_window() {
        let mut slot = PresetSlot::default();
        slot.state.time = 0.0;
        slot.preset_loaded_time = 0.0;
        let audio = onedrop_renderer::AudioLevels::default();
        // Local-window would yield progress = (1.0 / 16.0) ≈ 0.0625.
        tick_slot_evaluator(&mut slot, audio, 1.0, false, 16.0, Some(0.75));
        assert!((slot.state.progress - 0.75).abs() < 1e-6);
    }

    /// Override values outside `[0, 1]` get clamped — guards against
    /// MPRIS players reporting a position past the published length
    /// (Spotify ads, malformed metadata).
    #[test]
    fn track_progress_override_is_clamped() {
        let mut slot = PresetSlot::default();
        let audio = onedrop_renderer::AudioLevels::default();
        tick_slot_evaluator(&mut slot, audio, 0.016, false, 16.0, Some(1.42));
        assert!((slot.state.progress - 1.0).abs() < 1e-6);
        tick_slot_evaluator(&mut slot, audio, 0.016, false, 16.0, Some(-0.3));
        assert!((slot.state.progress - 0.0).abs() < 1e-6);
    }

    /// When no override is supplied, behaviour must match the
    /// historical local-window formula (regression guard for the
    /// `progress_ramps_across_display_window` integration test).
    #[test]
    fn no_override_falls_back_to_local_window() {
        let mut slot = PresetSlot::default();
        slot.state.time = 0.0;
        slot.preset_loaded_time = 0.0;
        let audio = onedrop_renderer::AudioLevels::default();
        tick_slot_evaluator(&mut slot, audio, 2.0, false, 4.0, None);
        // time = 2 s, duration = 4 s → progress = 0.5.
        assert!((slot.state.progress - 0.5).abs() < 1e-6);
    }
}