onedrop_renderer/

renderer.rs

//! Main renderer assembling the per-frame Milkdrop pipeline.
//!
//! Current pipeline (MVP):
//! 1. **Warp pass** — sample `prev_texture` at the per-vertex warped UV
//!    (computed CPU-side by [`onedrop-engine::warp_eval`]) and write to
//!    `render_texture`, applying decay + feedback filters in the fragment
//!    shader.
//! 2. **Copy-to-prev** — `render_texture` → `prev_texture` so next frame's
//!    warp pass can sample the previous frame's content.
//! 3. **Comp pass** — sample `render_texture`, apply display-only filters
//!    (currently just `gamma_adj`; user comp shaders later in sprint B2),
//!    write to `final_texture`. Filters here intentionally don't feed back
//!    into the warp loop.
//!
//! `final_texture` is what `render_texture()` exposes to the GUI/CLI.
//!
//! Future passes (waveforms, shapes, motion vectors, sprites, blur)
//! compose on top of this foundation.

use onedrop_codegen::{ShaderCompiler, ShaderUniforms, USER_TEXTURE_SLOTS};
use onedrop_hlsl::{TextureBindingPlan, UserSamplerRef, scan_user_samplers};

use crate::config::{RenderConfig, RenderState};
use crate::custom_shape::{CustomShapeBatch, CustomShapeInstance};
use crate::custom_wave::{CustomWaveBatch, CustomWaveVertex};
use crate::error::Result;
use crate::final_blend::FinalBlendPipeline;
use crate::gpu_context::GpuContext;
use crate::render_chain::RenderChain;
use crate::sprite_pipeline::{SpriteFrame, SpritePipeline, SpritePool};
use crate::text_pipeline::{TextFrame, TextPipeline};
use crate::texture_pool::TexturePool;
use crate::warp_mesh::WarpMesh;
use crate::warp_pipeline::WarpVertex;

use std::collections::hash_map::DefaultHasher;
use std::hash::{Hash, Hasher};

/// Fallback warp mesh resolution. Used by call-sites that bypass
/// `RenderConfig` (tests, benches). The real default comes from
/// `RenderConfig::mesh_cols`/`mesh_rows`, which `MeshQuality::Medium`
/// resolves to 48×36. MD2 ships 32×24 → 192×96.
pub const DEFAULT_MESH_COLS: u32 = 48;
pub const DEFAULT_MESH_ROWS: u32 = 36;

/// Main Milkdrop renderer.
///
/// Orchestrates one or two [`RenderChain`]s plus the final-blend pipeline
/// that composites their `final_texture` outputs into a single display
/// target. During a preset transition, the secondary chain is `Some` and
/// holds the outgoing preset's full pipeline; outside transitions it is
/// `None` and the blend pass passes the primary chain straight through.
pub struct MilkRenderer {
    gpu: GpuContext,
    /// Primary rendering chain — the currently active preset.
    chain: RenderChain,
    /// Secondary chain, active only during a preset transition. Holds the
    /// **outgoing** preset's state so it can keep evolving while the new
    /// preset takes over the primary slot.
    secondary: Option<RenderChain>,
    /// Final blend pass: lerps primary↔secondary `final_texture` into the
    /// display target by the transition progress. Passthrough of primary
    /// when no secondary chain is active.
    final_blend: FinalBlendPipeline,
    warp_mesh: WarpMesh,
    /// Primary chain's per-frame state (motion, wave, decay, gamma, audio,
    /// q1..q32, …). Pushed by the engine via `update_state`.
    state: RenderState,
    /// Secondary chain's per-frame state. Populated by the engine during
    /// preset transitions; `None` outside transitions. Each chain has its own
    /// `gamma_adj` / `echo_alpha` / audio / time — they advance independently
    /// while the blend pass crossfades their `final_texture` outputs.
    secondary_state: Option<RenderState>,
    /// Caches translated/validated user comp shaders by HLSL source. Letting
    /// the renderer own it keeps the codegen surface inside the crate that
    /// already depends on it; the engine just hands HLSL bytes over.
    shader_compiler: ShaderCompiler,
    /// User textures loaded from disk. Empty by default; the engine layer
    /// (GUI / CLI) populates it via `set_texture_pool`. The fallback 1×1
    /// white inside the pool is bound into any unfilled user-texture slot
    /// so the comp pass produces correct output for presets whose textures
    /// we don't have on disk.
    texture_pool: TexturePool,
    /// Sprite GPU pipeline (`MILK_IMG.INI` overlay). Shared by both
    /// chains during transitions — the pipeline is stateless past
    /// init, and the sprite frames the engine pushes are global, not
    /// per-preset.
    sprite_pipeline: SpritePipeline,
    /// Sprite texture pool: one texture per loaded `MILK_IMG.INI`
    /// entry, indexed by [`SpriteFrame::texture_index`].
    sprite_pool: SpritePool,
    /// Sprite render instances the engine pushed via
    /// [`Self::update_sprites`] for the next frame. Cleared on every
    /// `render` so a stale list doesn't outlive the engine tick.
    sprite_frames: Vec<SpriteFrame>,
    /// Text overlay (`MILK_MSG.INI` + MPRIS auto-title) pipeline.
    /// Renders on top of the final-blend output so messages never
    /// participate in the warp feedback loop.
    text_pipeline: TextPipeline,
    /// Text frames the engine pushed via [`Self::update_text_frames`]
    /// for the next render call.
    text_frames: Vec<TextFrame>,
}

impl MilkRenderer {
    /// Create a new renderer that owns its GPU device.
    pub async fn new(config: RenderConfig) -> Result<Self> {
        let gpu = GpuContext::new(config).await?;
        Self::from_gpu_context(gpu)
    }

    /// Create a renderer atop a shared GPU context.
    pub fn from_gpu_context(gpu: GpuContext) -> Result<Self> {
        let aspect = gpu.aspect_ratio();
        let cols = gpu.config.mesh_cols.max(2);
        let rows = gpu.config.mesh_rows.max(2);
        let warp_mesh = WarpMesh::new(cols, rows, aspect);
        let chain = RenderChain::new(&gpu, &warp_mesh)?;
        let final_blend = FinalBlendPipeline::new(
            &gpu.device,
            &gpu.config,
            &chain.textures().final_texture_view,
        )?;
        let texture_pool = TexturePool::new(&gpu.device, &gpu.queue);
        let sprite_pipeline = SpritePipeline::new(&gpu.device, gpu.config.texture_format.to_wgpu());
        let sprite_pool = SpritePool::new(&gpu.device, &gpu.queue);
        let text_pipeline =
            TextPipeline::new(&gpu.device, &gpu.queue, gpu.config.texture_format.to_wgpu());
        Ok(Self {
            gpu,
            chain,
            secondary: None,
            final_blend,
            warp_mesh,
            state: RenderState::default(),
            secondary_state: None,
            shader_compiler: ShaderCompiler::new(),
            texture_pool,
            sprite_pipeline,
            sprite_pool,
            sprite_frames: Vec::new(),
            text_pipeline,
            text_frames: Vec::new(),
        })
    }

    /// Swap in a populated [`TexturePool`]. The engine layer (GUI / CLI)
    /// calls this after constructing the renderer if the user has a
    /// texture directory configured. Pool population is best-effort
    /// (missing dirs are silently empty); see [`TexturePool::from_dirs`].
    pub fn set_texture_pool(&mut self, pool: TexturePool) {
        self.texture_pool = pool;
    }

    /// Borrow the texture pool. Used by the GUI's HUD to display "X user
    /// textures loaded" and by tests to assert pool wiring.
    pub fn texture_pool(&self) -> &TexturePool {
        &self.texture_pool
    }

    /// Borrow the underlying GPU device. Exposed so the engine layer can
    /// build a [`TexturePool`] before swapping it into the renderer.
    pub fn gpu_device(&self) -> std::sync::Arc<wgpu::Device> {
        self.gpu.device.clone()
    }

    /// Borrow the underlying GPU queue. Mirror of `gpu_device` for the
    /// pool-construction path.
    pub fn gpu_queue(&self) -> std::sync::Arc<wgpu::Queue> {
        self.gpu.queue.clone()
    }

    /// Format of the display texture that [`read_render_texture`] returns.
    /// Offline callers (CLI render-to-PNG, snapshot tests) use this to
    /// decide whether to swizzle BGRA → RGBA before encoding.
    pub fn render_format(&self) -> wgpu::TextureFormat {
        self.gpu.config.texture_format.to_wgpu()
    }

    /// Render-target width × height in pixels. Mirrors `RenderConfig`.
    pub fn render_size(&self) -> (u32, u32) {
        (self.gpu.config.width, self.gpu.config.height)
    }

    /// Install (or remove) the user comp shader for the active preset.
    ///
    /// Pass `Some(hlsl)` from the preset's `comp_shader` block to swap the
    /// comp pass into the user-authored pipeline. Pass `None` (or an empty
    /// `&str` after trimming) to revert to the engine's gamma-only default
    /// — the fallback for presets without a custom composite or for
    /// preset loads where the translation/validation chain failed.
    ///
    /// Return value:
    /// - `Ok(true)` — user shader compiled and is now active.
    /// - `Ok(false)` — translation or validation failed; the comp pipeline
    ///   is now on the default fallback. **Not** an error from the
    ///   renderer's perspective; the caller can surface a log line.
    /// - `Err(_)` — the wgpu device rejected the validated shader. Rare;
    ///   indicates either a wgpu/naga version skew or a
    ///   pipeline-construction bug.
    pub fn set_user_comp_shader(&mut self, hlsl: Option<&str>) -> Result<bool> {
        self.set_user_comp_shader_for_preset(hlsl, "")
    }

    /// Same as [`Self::set_user_comp_shader`], but lets the engine pass a
    /// `preset_id` that seeds the deterministic `sampler_rand0X` pick for
    /// this preset. Use the preset filename (`"Geiss - Aerial.milk"`) or
    /// any string stable for the preset's lifetime — same string → same
    /// rand selection.
    pub fn set_user_comp_shader_for_preset(
        &mut self,
        hlsl: Option<&str>,
        preset_id: &str,
    ) -> Result<bool> {
        let hlsl = match hlsl.map(str::trim).filter(|s| !s.is_empty()) {
            Some(s) => s,
            None => {
                self.chain
                    .comp_pipeline_mut()
                    .reset_to_default(&self.gpu.device);
                return Ok(true);
            }
        };

        // Scan for `sampler sampler_X;` declarations, resolve each through
        // the texture pool (literal names + `sampler_rand0X`), and build the
        // per-preset TextureBindingPlan before translating.
        let user_refs = scan_user_samplers(hlsl);
        let (plan, slot_views) = self.build_texture_plan(&user_refs, preset_id);

        match self
            .shader_compiler
            .compile_user_comp_shader_with_plan(hlsl, &plan)
        {
            Ok(compiled) => {
                self.chain.comp_pipeline_mut().set_user_shader_with_plan(
                    &self.gpu.device,
                    &compiled.source,
                    slot_views,
                )?;
                Ok(true)
            }
            Err(e) => {
                log::warn!("user comp shader failed to compile, falling back to default: {e}");
                self.chain
                    .comp_pipeline_mut()
                    .reset_to_default(&self.gpu.device);
                Ok(false)
            }
        }
    }

    /// Resolve a list of `sampler sampler_X;` references against the
    /// texture pool into a [`TextureBindingPlan`] + a parallel array of
    /// `wgpu::TextureView` slot bindings for the comp pipeline.
    ///
    /// - Literal logical names (`"clouds"`, `"worms"`) are looked up by
    ///   exact pool match.
    /// - `sampler_rand0X` (with optional name-prefix suffix) is resolved
    ///   to a deterministic-per-preset pick from the pool, optionally
    ///   filtered by the suffix.
    /// - Unresolvable names fall back to the 1×1 white texture.
    fn build_texture_plan(
        &self,
        refs: &[UserSamplerRef],
        preset_id: &str,
    ) -> (
        TextureBindingPlan,
        [Option<wgpu::TextureView>; USER_TEXTURE_SLOTS],
    ) {
        let mut plan = TextureBindingPlan::empty();
        let mut views: [Option<wgpu::TextureView>; USER_TEXTURE_SLOTS] = Default::default();

        // Group references by logical name so multi-alias references
        // (`sampler_clouds` + `sampler_fw_clouds`) collapse to one slot.
        let mut by_logical: std::collections::BTreeMap<&str, Vec<&UserSamplerRef>> =
            std::collections::BTreeMap::new();
        for r in refs {
            by_logical
                .entry(r.logical_name.as_str())
                .or_default()
                .push(r);
        }

        for (logical, aliases) in by_logical {
            let resolved = self.resolve_logical_texture(logical, preset_id);
            let pool_name = resolved.as_ref().map(|t| t.name.clone());
            let texsize = resolved
                .as_ref()
                .map(|t| t.texsize())
                .unwrap_or([1.0, 1.0, 1.0, 1.0]);

            let alias_specs: Vec<(String, &'static str)> = aliases
                .iter()
                .map(|a| (a.full_name.clone(), a.sampler_kind))
                .collect();
            let Some(slot) = plan.add_slot(pool_name, texsize, &alias_specs) else {
                continue; // cap exceeded — logged by add_slot
            };

            views[slot] = resolved.map(|t| t.view.clone());
        }

        (plan, views)
    }

    /// Resolve one logical texture name (e.g. `"clouds"`, `"rand02_smalltiled"`)
    /// to a concrete [`crate::UserTexture`] in the pool. `sampler_rand0X[_prefix]`
    /// patterns become deterministic picks seeded by the preset id; literal
    /// names are exact pool lookups.
    fn resolve_logical_texture(
        &self,
        logical: &str,
        preset_id: &str,
    ) -> Option<std::sync::Arc<crate::UserTexture>> {
        // `rand00..rand15` — optionally followed by `_<prefix>` to filter
        // the pool's candidate set.
        if let Some(rest) = logical.strip_prefix("rand") {
            // Two-digit slot suffix; treat any leading digits as the slot
            // index even when fewer than 2 are written.
            let mut slot_str = String::new();
            let mut prefix_part = "";
            for (i, c) in rest.char_indices() {
                if c.is_ascii_digit() {
                    slot_str.push(c);
                } else {
                    prefix_part = &rest[i..];
                    break;
                }
            }
            if !slot_str.is_empty() {
                let slot_index: u64 = slot_str.parse().unwrap_or(0);
                let prefix = prefix_part.trim_start_matches('_');
                let mut hasher = DefaultHasher::new();
                preset_id.hash(&mut hasher);
                slot_index.hash(&mut hasher);
                let seed = hasher.finish();
                return self
                    .texture_pool
                    .pick_rand(
                        seed,
                        if prefix.is_empty() {
                            None
                        } else {
                            Some(prefix)
                        },
                    )
                    .cloned();
            }
        }
        self.texture_pool.get(logical).cloned()
    }

    /// Whether the comp pass is currently driven by a user-authored
    /// shader (vs. the engine's gamma-only fallback). Surfaced for tests
    /// and the GUI's debug overlay.
    pub fn has_user_comp_shader(&self) -> bool {
        self.chain.comp_pipeline().has_user_shader()
    }

    /// Swap in a user-translated warp shader. Mirror of
    /// [`Self::set_user_comp_shader_for_preset`] but for the warp pass.
    /// The translation goes through the same `TextureBindingPlan`
    /// scan + texture-pool resolution as the comp side.
    pub fn set_user_warp_shader(&mut self, hlsl: Option<&str>) -> Result<bool> {
        self.set_user_warp_shader_for_preset(hlsl, "")
    }

    /// Same as [`Self::set_user_warp_shader`], with a `preset_id` that
    /// seeds the deterministic `sampler_rand0X` picks (filename works).
    pub fn set_user_warp_shader_for_preset(
        &mut self,
        hlsl: Option<&str>,
        preset_id: &str,
    ) -> Result<bool> {
        let hlsl = match hlsl.map(str::trim).filter(|s| !s.is_empty()) {
            Some(s) => s,
            None => {
                self.chain.warp_pipeline_mut().reset_to_default();
                return Ok(true);
            }
        };

        let user_refs = scan_user_samplers(hlsl);
        let (plan, slot_views) = self.build_texture_plan(&user_refs, preset_id);

        match self
            .shader_compiler
            .compile_user_warp_shader_with_plan(hlsl, &plan)
        {
            Ok(compiled) => {
                // Clone every view we need into owned handles *before*
                // borrowing `self.chain` mutably — the comp pipeline's
                // aux view ref would otherwise hold an immutable borrow
                // of `self.chain` for the whole call. Warp uses the
                // *previous* frame's blur pyramid (this frame's blur
                // doesn't exist yet at warp time); the noise pack is
                // shared with the comp pipeline.
                let textures = self.chain.textures();
                let prev_view = textures.prev_texture_view.clone();
                let prev_blur1 = textures.prev_blur1_texture_view.clone();
                let prev_blur2 = textures.prev_blur2_texture_view.clone();
                let prev_blur3 = textures.prev_blur3_texture_view.clone();
                let aux_owned = {
                    let aux = self.chain.comp_pipeline().comp_aux_views();
                    [
                        aux.noise_lq.clone(),
                        aux.noise_mq.clone(),
                        aux.noise_hq.clone(),
                        aux.noisevol_lq.clone(),
                        aux.noisevol_hq.clone(),
                    ]
                };
                let aux = crate::user_warp_pipeline::WarpAuxViews {
                    prev_blur1: &prev_blur1,
                    prev_blur2: &prev_blur2,
                    prev_blur3: &prev_blur3,
                    noise_lq: &aux_owned[0],
                    noise_mq: &aux_owned[1],
                    noise_hq: &aux_owned[2],
                    noisevol_lq: &aux_owned[3],
                    noisevol_hq: &aux_owned[4],
                };
                self.chain.warp_pipeline_mut().set_user_shader_with_plan(
                    &self.gpu.device,
                    &self.gpu.queue,
                    &compiled.source,
                    &prev_view,
                    &aux,
                    slot_views,
                )?;
                Ok(true)
            }
            Err(e) => {
                log::warn!("user warp shader failed to compile, falling back to default: {e}");
                self.chain.warp_pipeline_mut().reset_to_default();
                Ok(false)
            }
        }
    }

    /// Whether the warp pass is currently driven by a user-authored
    /// shader.
    pub fn has_user_warp_shader(&self) -> bool {
        self.chain.warp_pipeline().has_user_shader()
    }

    /// Update render state.
    pub fn update_state(&mut self, state: RenderState) {
        self.state = state;
    }

    /// Borrow the warp mesh for per-vertex equation evaluation.
    pub fn warp_mesh(&self) -> &WarpMesh {
        &self.warp_mesh
    }

    /// Rebuild the warp mesh at a different `cols × rows`. Reallocates
    /// the warp pipeline's vertex/index buffers on both the primary and
    /// (if active) secondary chains. The per-vertex equation executor in
    /// the engine reads `warp_mesh()` every frame and allocates its
    /// output vector fresh, so it adapts without further plumbing.
    ///
    /// `cols` and `rows` are clamped to `>= 2` to match `WarpMesh::new`.
    /// MD2 caps `nMeshSize` at 192×96; we mirror that ceiling so a
    /// runaway slider can't allocate gigabytes of index buffer.
    pub fn set_mesh_size(&mut self, cols: u32, rows: u32) {
        let cols = cols.clamp(2, 192);
        let rows = rows.clamp(2, 96);
        if cols == self.warp_mesh.cols && rows == self.warp_mesh.rows {
            return;
        }
        let aspect = self.gpu.aspect_ratio();
        self.warp_mesh = WarpMesh::new(cols, rows, aspect);
        self.chain
            .rebuild_warp_mesh(&self.gpu.device, &self.warp_mesh);
        if let Some(secondary) = self.secondary.as_mut() {
            secondary.rebuild_warp_mesh(&self.gpu.device, &self.warp_mesh);
        }
        self.gpu.config.mesh_cols = cols;
        self.gpu.config.mesh_rows = rows;
    }

    /// Current warp mesh size as `(cols, rows)`. Used by the GUI's
    /// options panel to seed its widget state.
    pub fn mesh_size(&self) -> (u32, u32) {
        (self.warp_mesh.cols, self.warp_mesh.rows)
    }

    /// Push freshly computed warp UVs to the GPU. Also caches them on
    /// the chain so the motion-vector pass can build anisotropic
    /// segments aligned with the local warp displacement.
    pub fn update_warp_vertices(&mut self, vertices: &[WarpVertex]) {
        let cols = self.warp_mesh.cols;
        let rows = self.warp_mesh.rows;
        self.chain
            .update_warp_vertices(&self.gpu.queue, cols, rows, vertices);
    }

    /// Push a fresh mono audio sample window for the waveform pass.
    ///
    /// The renderer applies `wave_smoothing` (single-pole IIR) on the
    /// CPU side before upload — pass the raw samples; smoothing follows
    /// `RenderState::wave.smoothing`. The buffer is clamped to
    /// `NUM_WAVE_SAMPLES`; shorter inputs are zero-padded.
    ///
    /// `instantaneous_volume` is the frame-mean abs value used by
    /// `b_mod_wave_alpha_by_volume` to scale the wave alpha — pass
    /// `(|bass| + |mid| + |treb|) / 3` or any equivalent volume proxy
    /// in `[0, 1]`.
    pub fn update_waveform_samples(&mut self, samples: &[f32], instantaneous_volume: f32) {
        self.chain.update_waveform_samples(
            &self.gpu.queue,
            samples,
            instantaneous_volume,
            self.state.wave,
        );
    }

    /// Stereo variant of [`Self::update_waveform_samples`] — uploads
    /// distinct left and right channels so the waveform pass can lay
    /// them on the upper and lower screen halves when
    /// `WaveParams::split_lr` is `true`.
    pub fn update_waveform_samples_lr(
        &mut self,
        left: &[f32],
        right: &[f32],
        instantaneous_volume: f32,
    ) {
        self.chain.update_waveform_samples_lr(
            &self.gpu.queue,
            left,
            right,
            instantaneous_volume,
            self.state.wave,
        );
    }

    /// Borrow the current waveform sample buffer. Mostly useful for
    /// tests that want to assert the smoothing applied or the latest
    /// upload's length.
    pub fn wave_samples(&self) -> &[f32] {
        self.chain.wave_samples()
    }

    /// Upload the per-frame custom-wave vertex stream.
    pub fn update_custom_waves(
        &mut self,
        vertices: &[CustomWaveVertex],
        batches: &[CustomWaveBatch],
    ) {
        self.chain
            .update_custom_waves(&self.gpu.queue, vertices, batches);
    }

    pub fn custom_wave_vertex_count(&self) -> u32 {
        self.chain.custom_wave_vertex_count()
    }

    pub fn custom_wave_batch_count(&self) -> usize {
        self.chain.custom_wave_batch_count()
    }

    /// Upload the per-frame custom-shape instance stream.
    pub fn update_custom_shapes(
        &mut self,
        instances: &[CustomShapeInstance],
        batches: &[CustomShapeBatch],
    ) {
        let aspect = self.gpu.aspect_ratio();
        self.chain
            .update_custom_shapes(&self.gpu.queue, instances, batches, aspect);
    }

    pub fn custom_shape_instance_count(&self) -> u32 {
        self.chain.custom_shape_instance_count()
    }

    pub fn custom_shape_batch_count(&self) -> usize {
        self.chain.custom_shape_batch_count()
    }

    pub fn border_batch_count(&self) -> usize {
        self.chain.border_batch_count()
    }

    pub fn motion_vector_segment_count(&self) -> u32 {
        self.chain.motion_vector_segment_count()
    }

    /// Push the sprite frame list for the next [`Self::render`] call.
    /// The engine ticks its `SpriteManager` and feeds the resulting
    /// [`SpriteFrame`] list here. Empty slice = no sprite pass recorded
    /// next frame.
    pub fn update_sprites(&mut self, frames: &[SpriteFrame]) {
        self.sprite_frames.clear();
        self.sprite_frames.extend_from_slice(frames);
    }

    /// Number of sprite frames queued for the next render call.
    /// Exposed for tests + the GUI's HUD.
    pub fn sprite_frame_count(&self) -> usize {
        self.sprite_frames.len()
    }

    /// Reload sprite textures from a directory, in the order of the
    /// parsed `MILK_IMG.INI` entries. `def_imgs` is the parallel list
    /// of `img=` filenames the engine pulled from the parser. Missing
    /// files are silently substituted with a 1×1 transparent fallback;
    /// the engine's `texture_index` mapping stays dense.
    pub fn load_sprite_defs(&mut self, dir: &std::path::Path, def_imgs: &[String]) {
        self.sprite_pool
            .load_from_defs(&self.gpu.device, &self.gpu.queue, dir, def_imgs);
    }

    /// Borrow the sprite pool. Used by tests + GUI HUD.
    pub fn sprite_pool(&self) -> &SpritePool {
        &self.sprite_pool
    }

    /// Push the text-overlay frame list for the next [`Self::render`]
    /// call. The engine ticks its `MessageManager` (+ optional MPRIS
    /// auto-title) and forwards the resulting [`TextFrame`] list.
    /// Empty slice = no text pass.
    pub fn update_text_frames(&mut self, frames: &[TextFrame]) {
        self.text_frames.clear();
        self.text_frames.extend_from_slice(frames);
    }

    /// Number of text frames queued for next render.
    pub fn text_frame_count(&self) -> usize {
        self.text_frames.len()
    }

    /// Number of glyphs currently cached in the text atlas. Test
    /// surface — grows on the first frame each glyph is requested.
    pub fn text_atlas_glyph_count(&self) -> usize {
        self.text_pipeline.atlas().glyph_count()
    }

    /// Render a frame: record every per-chain pass (primary + optional
    /// secondary) plus the final blend, copy warp outputs into their
    /// feedback buffers, and submit. When no secondary chain is active the
    /// blend pass acts as a passthrough of the primary chain's
    /// `final_texture`.
    pub fn render(&mut self) -> Result<()> {
        let primary_uniforms = build_shader_uniforms_from(&self.state, &self.gpu);

        let mut encoder = self
            .gpu
            .device
            .create_command_encoder(&wgpu::CommandEncoderDescriptor {
                label: Some("MilkRenderer Encoder"),
            });

        self.chain.record_passes(
            &self.gpu,
            &mut encoder,
            &self.state,
            &primary_uniforms,
            &self.sprite_pipeline,
            &self.sprite_pool,
            &self.sprite_frames,
        );

        // V.3 — drive the secondary chain with its own state (outgoing
        // preset). Falls back to the primary state when the engine hasn't
        // pushed a secondary state yet (transition just started).
        // Sprites are global (not per-preset), so the secondary chain
        // sees the *same* frames as the primary; the blend pass merges
        // them at the comp output.
        if let Some(secondary) = self.secondary.as_mut() {
            let sec_state = self.secondary_state.as_ref().unwrap_or(&self.state);
            let sec_uniforms = build_shader_uniforms_from(sec_state, &self.gpu);
            secondary.record_passes(
                &self.gpu,
                &mut encoder,
                sec_state,
                &sec_uniforms,
                &self.sprite_pipeline,
                &self.sprite_pool,
                &self.sprite_frames,
            );
        }

        // Final blend: lerp primary↔secondary into the display texture.
        // Passthrough of primary when `secondary` is `None`.
        self.final_blend.record_pass(&mut encoder);

        // Text overlay: draws messages on top of the blended output.
        // Lives AFTER `final_blend` so it never feeds back through
        // the warp loop (MD2's message overlay sits at the same
        // stage — display-only, no smearing).
        if !self.text_frames.is_empty() {
            self.text_pipeline.record(
                &mut encoder,
                &self.gpu.queue,
                &self.gpu.device,
                self.final_blend.display_texture_view(),
                &self.text_frames,
                self.gpu.config.width,
                self.gpu.config.height,
            );
        }

        // Preserve each chain's warp output for next frame's feedback AFTER
        // the comp pass has consumed `prev_texture`. The comp pass sees
        // frame N-1's warp output for echo; gamma still stays out of the
        // feedback loop because copy_to_prev sources `render_texture`
        // (untouched by comp).
        self.chain.copy_to_prev(&mut encoder, &self.gpu);
        if let Some(secondary) = self.secondary.as_ref() {
            secondary.copy_to_prev(&mut encoder, &self.gpu);
        }

        self.gpu.queue.submit(std::iter::once(encoder.finish()));

        self.state.frame += 1;
        if let Some(s) = self.secondary_state.as_mut() {
            s.frame += 1;
        }
        Ok(())
    }

    /// Begin a preset transition: swap the current primary chain into the
    /// secondary slot (where it keeps fading out the outgoing preset) and
    /// allocate a fresh primary chain for the incoming preset.
    ///
    /// The blend pass is rebound so the **secondary** view points at the
    /// outgoing preset (the old primary) and the **primary** view at the
    /// new chain. `progress` starts at `0` (full secondary visible) and
    /// the engine ramps it to `1` over the transition duration.
    ///
    /// Returns `Err` only if the new primary chain fails to allocate (rare
    /// — a wgpu error).
    pub fn start_transition(&mut self) -> Result<()> {
        // If a transition is already in flight, drop the previous outgoing
        // chain. The engine should normally not call this twice without
        // letting the first transition finish; this is a safety net.
        self.secondary = None;

        let new_primary = RenderChain::new(&self.gpu, &self.warp_mesh)?;
        let outgoing = std::mem::replace(&mut self.chain, new_primary);
        self.install_secondary_chain(outgoing);
        Ok(())
    }

    /// Install a caller-built secondary chain at the start of a preset
    /// transition. The renderer's blend pass starts sourcing from it
    /// immediately; the caller drives `set_transition_progress` each
    /// frame until completion. Most callers want
    /// [`Self::start_transition`] instead — this overload exists for
    /// tests and for reclaiming a previous chain's textures.
    pub fn install_secondary_chain(&mut self, chain: RenderChain) {
        self.final_blend.set_inputs(
            &self.gpu.device,
            &self.chain.textures().final_texture_view,
            Some(&chain.textures().final_texture_view),
        );
        self.final_blend.update_progress(&self.gpu.queue, 0.0, true);
        self.secondary = Some(chain);
    }

    /// Drop the secondary chain at transition end and rebind the blend
    /// pass to passthrough of the primary chain.
    pub fn clear_secondary_chain(&mut self) -> Option<RenderChain> {
        self.final_blend.set_inputs(
            &self.gpu.device,
            &self.chain.textures().final_texture_view,
            None,
        );
        self.final_blend
            .update_progress(&self.gpu.queue, 0.0, false);
        self.secondary.take()
    }

    /// Push the current transition progress (in `[0, 1]`) into the blend
    /// pass uniform. `0` = full secondary (outgoing preset); `1` = full
    /// primary (incoming preset). Caller is expected to feed the eased
    /// value from the engine's `TransitionManager`.
    pub fn set_transition_progress(&self, progress: f32) {
        self.final_blend
            .update_progress(&self.gpu.queue, progress, self.secondary.is_some());
    }

    /// Borrow the secondary chain mutably — used by the engine to push
    /// the outgoing preset's warp vertices / audio samples / etc. while
    /// the transition is in flight. `None` outside transitions.
    pub fn secondary_chain_mut(&mut self) -> Option<&mut RenderChain> {
        self.secondary.as_mut()
    }

    /// Whether a secondary chain is currently active (a transition is in
    /// flight).
    pub fn is_transitioning(&self) -> bool {
        self.secondary.is_some()
    }

    /// Get the displayable texture: the final-blend pass output that
    /// composites primary + optional secondary chains. The GUI/CLI sample
    /// from this for presentation.
    ///
    /// The name is kept for backwards compatibility with the pre-comp-pass
    /// API (the GUI's render path imports it as
    /// `engine.renderer().render_texture()`); renaming would be a breaking
    /// change for consumers.
    #[allow(clippy::misnamed_getters)]
    pub fn render_texture(&self) -> &wgpu::Texture {
        self.final_blend.display_texture()
    }

    /// Get the warp pass output before comp filtering. Useful for tests that
    /// want to assert on the feedback chain content directly, bypassing
    /// `gamma_adj` and any future display-only adjustments.
    pub fn warp_output_texture(&self) -> &wgpu::Texture {
        &self.chain.textures().render_texture
    }

    /// Read the current `final_texture` back as tightly-packed **RGBA8**
    /// bytes (`width * height * 4`). Reflects what the screen shows
    /// (post-comp), matching `render_texture()`. The byte order is
    /// always R, G, B, A regardless of the surface format — BGRA
    /// surfaces (the desktop default) are swizzled on the CPU before
    /// the buffer returns so callers never have to branch on format.
    ///
    /// This is a synchronous CPU stall — intended for tests and offline
    /// snapshots, not the hot rendering path. Wgpu requires the per-row
    /// staging stride to be 256-byte aligned, so the helper copies into a
    /// padded staging buffer and unpads it before returning.
    pub fn read_render_texture(&self) -> Result<Vec<u8>> {
        let width = self.gpu.config.width;
        let height = self.gpu.config.height;
        let bytes_per_pixel: u32 = 4;
        let unpadded_row = width * bytes_per_pixel;
        let align = wgpu::COPY_BYTES_PER_ROW_ALIGNMENT;
        let padded_row = unpadded_row.div_ceil(align) * align;

        let staging = self.gpu.device.create_buffer(&wgpu::BufferDescriptor {
            label: Some("Render Texture Readback Staging"),
            size: (padded_row * height) as u64,
            usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ,
            mapped_at_creation: false,
        });

        let mut encoder = self
            .gpu
            .device
            .create_command_encoder(&wgpu::CommandEncoderDescriptor {
                label: Some("Readback Encoder"),
            });
        encoder.copy_texture_to_buffer(
            wgpu::TexelCopyTextureInfo {
                texture: self.final_blend.display_texture(),
                mip_level: 0,
                origin: wgpu::Origin3d::ZERO,
                aspect: wgpu::TextureAspect::All,
            },
            wgpu::TexelCopyBufferInfo {
                buffer: &staging,
                layout: wgpu::TexelCopyBufferLayout {
                    offset: 0,
                    bytes_per_row: Some(padded_row),
                    rows_per_image: Some(height),
                },
            },
            wgpu::Extent3d {
                width,
                height,
                depth_or_array_layers: 1,
            },
        );
        self.gpu.queue.submit(std::iter::once(encoder.finish()));

        let slice = staging.slice(..);
        let (tx, rx) = std::sync::mpsc::channel();
        slice.map_async(wgpu::MapMode::Read, move |res| {
            let _ = tx.send(res);
        });
        self.gpu
            .device
            .poll(wgpu::PollType::wait_indefinitely())
            .ok();
        rx.recv()
            .map_err(|e| crate::error::RenderError::RenderFailed(e.to_string()))?
            .map_err(|e| crate::error::RenderError::RenderFailed(format!("{e:?}")))?;

        let view = slice.get_mapped_range();
        let mut out = Vec::with_capacity((unpadded_row * height) as usize);
        for row in 0..height {
            let start = (row * padded_row) as usize;
            let end = start + unpadded_row as usize;
            out.extend_from_slice(&view[start..end]);
        }
        drop(view);
        staging.unmap();

        // Normalise to RGBA8 byte order. BGRA8 (desktop default on most
        // backends) gets its R/B channels swapped in place.
        let fmt = self.gpu.config.texture_format.to_wgpu();
        if matches!(
            fmt,
            wgpu::TextureFormat::Bgra8Unorm | wgpu::TextureFormat::Bgra8UnormSrgb
        ) {
            for px in out.chunks_exact_mut(4) {
                px.swap(0, 2);
            }
        }

        Ok(out)
    }

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

    /// Push the outgoing preset's `RenderState` for the secondary chain.
    /// Called by the engine each frame during a transition; cleared by
    /// passing `None` once the transition completes.
    pub fn update_secondary_state(&mut self, state: Option<RenderState>) {
        self.secondary_state = state;
    }

    /// Push the outgoing preset's per-vertex warp UVs to the secondary
    /// chain. No-op when no secondary chain is active. Mirrors
    /// `update_warp_vertices` for the primary chain.
    pub fn update_secondary_warp_vertices(&mut self, vertices: &[WarpVertex]) {
        let cols = self.warp_mesh.cols;
        let rows = self.warp_mesh.rows;
        if let Some(sec) = self.secondary.as_mut() {
            sec.update_warp_vertices(&self.gpu.queue, cols, rows, vertices);
        }
    }

    /// Push the outgoing preset's audio samples to the secondary chain's
    /// waveform pass. No-op when no secondary chain is active. The
    /// `wave_params` argument carries the smoothing factor for the IIR.
    pub fn update_secondary_waveform_samples(
        &mut self,
        samples: &[f32],
        instantaneous_volume: f32,
        wave_params: crate::config::WaveParams,
    ) {
        if let Some(sec) = self.secondary.as_mut() {
            sec.update_waveform_samples(
                &self.gpu.queue,
                samples,
                instantaneous_volume,
                wave_params,
            );
        }
    }

    /// Stereo variant of `update_secondary_waveform_samples` for the
    /// outgoing preset during a transition. Mirrors the primary
    /// chain's `update_waveform_samples_lr`.
    pub fn update_secondary_waveform_samples_lr(
        &mut self,
        left: &[f32],
        right: &[f32],
        instantaneous_volume: f32,
        wave_params: crate::config::WaveParams,
    ) {
        if let Some(sec) = self.secondary.as_mut() {
            sec.update_waveform_samples_lr(
                &self.gpu.queue,
                left,
                right,
                instantaneous_volume,
                wave_params,
            );
        }
    }

    /// Push the outgoing preset's custom-wave vertex stream to the secondary
    /// chain. No-op when no secondary chain is active.
    pub fn update_secondary_custom_waves(
        &mut self,
        vertices: &[CustomWaveVertex],
        batches: &[CustomWaveBatch],
    ) {
        if let Some(sec) = self.secondary.as_mut() {
            sec.update_custom_waves(&self.gpu.queue, vertices, batches);
        }
    }

    /// Push the outgoing preset's custom-shape instance stream to the
    /// secondary chain. No-op when no secondary chain is active.
    pub fn update_secondary_custom_shapes(
        &mut self,
        instances: &[CustomShapeInstance],
        batches: &[CustomShapeBatch],
    ) {
        let aspect = self.gpu.aspect_ratio();
        if let Some(sec) = self.secondary.as_mut() {
            sec.update_custom_shapes(&self.gpu.queue, instances, batches, aspect);
        }
    }

    /// Resize render targets. Re-allocates per-chain textures, the blend
    /// display target, and rebinds the blend pass to the new primary view.
    pub fn resize(&mut self, width: u32, height: u32) {
        self.gpu.set_resolution(width, height);
        self.warp_mesh = WarpMesh::new(
            self.warp_mesh.cols,
            self.warp_mesh.rows,
            self.gpu.aspect_ratio(),
        );
        self.chain.resize(&self.gpu);
        if let Some(secondary) = self.secondary.as_mut() {
            secondary.resize(&self.gpu);
        }
        self.final_blend.resize(&self.gpu.device, &self.gpu.config);
        let secondary_view = self
            .secondary
            .as_ref()
            .map(|s| s.textures().final_texture_view.clone());
        self.final_blend.set_inputs(
            &self.gpu.device,
            &self.chain.textures().final_texture_view,
            secondary_view.as_ref(),
        );
    }
}

/// Build the `ShaderUniforms` payload from any `RenderState` + GPU context.
/// Shared between the primary and secondary render paths so each chain can
/// run with its own `gamma_adj` / `echo_alpha` / audio / q snapshot.
fn build_shader_uniforms_from(state: &RenderState, gpu: &GpuContext) -> ShaderUniforms {
    let aspect = gpu.aspect_ratio();
    let aspect_x = if aspect > 1.0 { 1.0 / aspect } else { 1.0 };
    let aspect_y = if aspect < 1.0 { aspect } else { 1.0 };
    let w = gpu.config.width as f32;
    let h = gpu.config.height as f32;
    let audio = &state.audio;
    let mut u = ShaderUniforms {
        time: state.time,
        frame: state.frame as f32,
        progress: state.progress,
        bass: audio.bass,
        mid: audio.mid,
        treb: audio.treb,
        vol: (audio.bass + audio.mid + audio.treb) / 3.0,
        bass_att: audio.bass_att,
        mid_att: audio.mid_att,
        treb_att: audio.treb_att,
        vol_att: (audio.bass_att + audio.mid_att + audio.treb_att) / 3.0,
        gamma_adj: state.gamma_adj,
        echo_zoom: state.echo_zoom,
        echo_alpha: state.echo_alpha,
        echo_orient: state.echo_orient as f32,
        red_blue_stereo: if state.red_blue_stereo { 1.0 } else { 0.0 },
        aspect: [aspect_x, aspect_y, 1.0 / aspect_x, 1.0 / aspect_y],
        texsize: [w, h, 1.0 / w, 1.0 / h],
        hue_shader: hue_shader_for(state.time),
        ..ShaderUniforms::default()
    };
    u.set_q_channels(&state.q_snapshot);
    u
}

/// Time-driven RGB tint MD2 cycles through each frame. Three oscillators
/// with mutually-prime periods produce a slow rainbow rotation that
/// never repeats (rationals on the unit circle); presets that multiply
/// `ret * hue_shader` get the rainbow rotation MD2 is tuned for, while
/// presets that ignore it keep their authored colour palette because
/// the per-channel output stays in `[0, 1]` and floats around `~0.5`.
/// `.w` is reserved for a future per-corner mix factor.
fn hue_shader_for(time: f32) -> [f32; 4] {
    let r = 0.5 + 0.5 * (time * 0.34 + 1.0).cos();
    let g = 0.5 + 0.5 * (time * 0.47 + 2.0).cos();
    let b = 0.5 + 0.5 * (time * 0.27 + 3.0).cos();
    [r, g, b, 0.0]
}

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

    #[test]
    fn test_renderer_creation() {
        let config = RenderConfig::default();
        let renderer = pollster::block_on(MilkRenderer::new(config));
        assert!(renderer.is_ok());
    }

    #[test]
    fn test_render_frame() {
        let config = RenderConfig::default();
        let mut renderer = pollster::block_on(MilkRenderer::new(config)).unwrap();
        let result = renderer.render();
        assert!(result.is_ok());
    }

    #[test]
    fn test_render_texture() {
        let config = RenderConfig::default();
        let width = config.width;
        let height = config.height;
        let renderer = pollster::block_on(MilkRenderer::new(config)).unwrap();
        let texture = renderer.render_texture();
        assert_eq!(texture.width(), width);
        assert_eq!(texture.height(), height);
    }

    #[test]
    fn test_multiple_renders() {
        let config = RenderConfig::default();
        let mut renderer = pollster::block_on(MilkRenderer::new(config)).unwrap();
        for _ in 0..10 {
            assert!(renderer.render().is_ok());
        }
        assert_eq!(renderer.state().frame, 10);
    }

    /// `set_user_comp_shader` end-to-end: a real, simple MD2-style HLSL body
    /// must translate, validate, and end up driving the comp pass. The
    /// `has_user_comp_shader()` flag is the visible test surface; the
    /// pipeline-level swap is exercised by the comp_pipeline tests.
    #[test]
    fn user_comp_shader_swap_via_renderer_api() {
        let mut r = pollster::block_on(MilkRenderer::new(RenderConfig::default())).unwrap();
        // The single-line MD2-style body the translator handles cleanly:
        // brace-stripped wrapper, `tex2D`/`saturate` already covered, no
        // implicit-broadcast traps.
        let hlsl = "shader_body { ret = tex2D(sampler_main, uv).xyz; ret *= 1.5; }";
        let ok = r
            .set_user_comp_shader(Some(hlsl))
            .expect("compile path must not error on valid HLSL");
        assert!(ok, "expected compile success, got fallback");
        assert!(r.has_user_comp_shader());

        // None reverts to default.
        let _ = r.set_user_comp_shader(None);
        assert!(!r.has_user_comp_shader());
    }

    /// Mirror of `user_comp_shader_swap_via_renderer_api` for the warp
    /// pipeline. Same MD2-style body shape; the renderer's API flips the
    /// warp pass from the engine's hand-written `warp.wgsl` to a
    /// translated user pipeline. The reset path (`None`) returns to the
    /// default warp.
    #[test]
    fn user_warp_shader_swap_via_renderer_api() {
        let mut r = pollster::block_on(MilkRenderer::new(RenderConfig::default())).unwrap();
        let hlsl = "shader_body { ret = tex2D(sampler_main, uv).xyz * 0.9; ret -= 0.01; }";
        let ok = r
            .set_user_warp_shader(Some(hlsl))
            .expect("compile path must not error on valid HLSL");
        assert!(ok, "expected warp compile success, got fallback");
        assert!(r.has_user_warp_shader());

        // The render loop must keep working — a frame draws with the
        // user pipeline active.
        assert!(r.render().is_ok());

        // Reset reverts to the default warp.
        let _ = r.set_user_warp_shader(None);
        assert!(!r.has_user_warp_shader());
        assert!(r.render().is_ok());
    }

    /// Invalid warp HLSL must NOT propagate as an error — same contract
    /// the comp side honours. The pass falls back to the default
    /// `warp.wgsl`, the renderer reports `Ok(false)`, and the frame
    /// still draws.
    #[test]
    fn user_warp_shader_invalid_hlsl_falls_back_gracefully() {
        let mut r = pollster::block_on(MilkRenderer::new(RenderConfig::default())).unwrap();
        let ok = r
            .set_user_warp_shader(Some("not HLSL @@@ {{{"))
            .expect("invalid input must not bubble up as renderer error");
        assert!(!ok);
        assert!(!r.has_user_warp_shader());
        assert!(r.render().is_ok());
    }

    /// Garbage HLSL must NOT propagate as an error from the renderer — the
    /// comp pass falls back to the default and reports `Ok(false)`. This is
    /// the contract the engine relies on to keep navigation usable when a
    /// preset's shader can't be translated.
    #[test]
    fn user_comp_shader_invalid_hlsl_falls_back_gracefully() {
        let mut r = pollster::block_on(MilkRenderer::new(RenderConfig::default())).unwrap();
        let ok = r
            .set_user_comp_shader(Some(
                "this is not even close to HLSL — squiggly braces { everywhere",
            ))
            .expect("invalid input must not bubble up as renderer error");
        assert!(!ok, "expected fallback, got success");
        assert!(!r.has_user_comp_shader());
        // Renderer still renders cleanly with the default shader.
        assert!(r.render().is_ok());
    }

    /// Noise sampling end-to-end: a user comp shader that samples the
    /// procedural noise pack must translate, validate, and drive the comp
    /// pass. This covers the noise sampler bindings (6–10) and the
    /// sampler variants (`sampler_pw_main` → `sampler_pw`): the translator
    /// emits distinct bindings, the wrapper declares them, and the
    /// renderer binds them.
    #[test]
    fn noise_sampling_user_shader_compiles_through_renderer() {
        let mut r = pollster::block_on(MilkRenderer::new(RenderConfig::default())).unwrap();
        let hlsl = "shader_body {\n\
            ret = tex2D(sampler_noise_lq, uv).xyz;\n\
            ret += tex2D(sampler_pw_noise_hq, uv * 4).xyz * 0.25;\n\
            ret += tex3D(sampler_noisevol_hq, vec3<f32>(uv, time)).xyz * 0.5;\n\
            ret *= tex2D(sampler_pw_main, uv).xyz + 0.25;\n\
        }";
        let ok = r
            .set_user_comp_shader(Some(hlsl))
            .expect("compile path must not error");
        assert!(
            ok,
            "noise-sampling shader should compile through noise bindings"
        );
        assert!(r.has_user_comp_shader());
        // Renderer can drive a frame with this shader bound — covers
        // pipeline draw with the full 15-binding bind group.
        assert!(r.render().is_ok());
    }

    /// Empty / whitespace-only HLSL is treated as "no user shader" — same
    /// path as `None`. Avoids a needless compile attempt for presets that
    /// declare `comp_shader=` with no content.
    #[test]
    fn user_comp_shader_empty_input_resets_to_default() {
        let mut r = pollster::block_on(MilkRenderer::new(RenderConfig::default())).unwrap();
        // Install a real one first…
        let _ = r
            .set_user_comp_shader(Some("shader_body { ret = vec3<f32>(1, 0, 0); }"))
            .unwrap();
        assert!(r.has_user_comp_shader());
        // …then reset via empty.
        let ok = r.set_user_comp_shader(Some("   \n\t  ")).unwrap();
        assert!(ok);
        assert!(!r.has_user_comp_shader());
    }

    #[test]
    fn warp_mesh_exposed() {
        let cfg = RenderConfig::default();
        let r = pollster::block_on(MilkRenderer::new(cfg)).unwrap();
        let m = r.warp_mesh();
        assert_eq!(m.cols, DEFAULT_MESH_COLS);
        assert_eq!(m.rows, DEFAULT_MESH_ROWS);
        assert_eq!(
            m.vertex_count(),
            (DEFAULT_MESH_COLS * DEFAULT_MESH_ROWS) as usize
        );
    }

    // -----------------------------------------------------------------
    // User-loaded textures + sampler_rand0X end-to-end
    // -----------------------------------------------------------------

    /// Helper: write a 4×4 solid-colour PNG so a test can synthesise a pool
    /// without checking fixtures into the repo. Returns the tempdir handle
    /// so the file lives as long as the binding.
    fn make_texture_pool(
        gpu_device: &wgpu::Device,
        gpu_queue: &wgpu::Queue,
        names: &[&str],
    ) -> (tempfile::TempDir, crate::TexturePool) {
        let dir = tempfile::tempdir().unwrap();
        for n in names {
            let path = dir.path().join(format!("{n}.png"));
            let pixels: Vec<u8> = (0..16).flat_map(|_| [10u8, 20, 30, 255]).collect();
            let img = image::RgbaImage::from_raw(4, 4, pixels).unwrap();
            img.save_with_format(&path, image::ImageFormat::Png)
                .unwrap();
        }
        let pool =
            crate::TexturePool::from_dirs(gpu_device, gpu_queue, &[dir.path().to_path_buf()]);
        (dir, pool)
    }

    /// A preset that samples a disk-loaded `sampler_clouds` must compile
    /// successfully when the renderer's pool has that texture loaded.
    /// The translator lands the sampler on its user-texture binding
    /// instead of falling back to `sampler_main` with a
    /// `/*was: sampler_clouds*/` debug comment.
    #[test]
    fn user_texture_drives_user_shader_compile() {
        let mut r = pollster::block_on(MilkRenderer::new(RenderConfig::default())).unwrap();
        let (_keepalive, pool) =
            make_texture_pool(r.gpu.device.as_ref(), r.gpu.queue.as_ref(), &["clouds"]);
        r.set_texture_pool(pool);
        assert_eq!(r.texture_pool().len(), 1);

        let hlsl = "sampler sampler_clouds;\n\
                    shader_body { ret = tex2D(sampler_clouds, uv).xyz; }";
        let ok = r
            .set_user_comp_shader(Some(hlsl))
            .expect("plan-driven compile must not error");
        assert!(ok, "expected user-texture compile to succeed");
        assert!(r.has_user_comp_shader());
        assert!(r.render().is_ok());
    }

    /// `sampler_rand02` resolves to a pool texture deterministically per
    /// preset id. Same id → same texture binding; different ids → may
    /// differ. The test asserts the deterministic-per-id contract.
    #[test]
    fn sampler_rand0x_resolves_deterministically_per_preset() {
        let mut r = pollster::block_on(MilkRenderer::new(RenderConfig::default())).unwrap();
        let (_keepalive, pool) = make_texture_pool(
            r.gpu.device.as_ref(),
            r.gpu.queue.as_ref(),
            &["alpha", "beta", "gamma"],
        );
        r.set_texture_pool(pool);

        let hlsl = "sampler sampler_rand02;\n\
                    shader_body { ret = tex2D(sampler_rand02, uv).xyz; }";

        // Same preset id twice → same compilation result.
        let ok_a = r
            .set_user_comp_shader_for_preset(Some(hlsl), "Geiss - Aerial.milk")
            .unwrap();
        assert!(ok_a);
        let ok_b = r
            .set_user_comp_shader_for_preset(Some(hlsl), "Geiss - Aerial.milk")
            .unwrap();
        assert!(ok_b);
        // Different preset id is *allowed* to pick the same texture
        // (small pools have collisions) — we only test the no-error and
        // no-fallback path, not that the choice differs.
        let ok_c = r
            .set_user_comp_shader_for_preset(Some(hlsl), "Krash - Mandala.milk")
            .unwrap();
        assert!(ok_c);
    }

    /// A user shader referencing a missing pool texture must still compile
    /// (binding routed through the user slot, but bound to the fallback
    /// 1×1 white texture). Sampling produces `vec4(1, 1, 1, 1)` so the
    /// preset's math still terminates in a valid output.
    #[test]
    fn missing_user_texture_uses_fallback_not_error() {
        let mut r = pollster::block_on(MilkRenderer::new(RenderConfig::default())).unwrap();
        // No pool populated — only the fallback.
        let hlsl = "sampler sampler_clouds;\n\
                    shader_body { ret = tex2D(sampler_clouds, uv).xyz; }";
        let ok = r
            .set_user_comp_shader(Some(hlsl))
            .expect("missing texture must not surface as renderer error");
        assert!(ok);
        assert!(r.has_user_comp_shader());
        assert!(r.render().is_ok());
    }

    // -----------------------------------------------------------------
    // Waveform pass dispatched end-to-end
    // -----------------------------------------------------------------

    /// Every MD2 wave mode (0..7) must render without panicking through
    /// the dispatched wave pass. We seed deterministic sample data, set
    /// the mode, and read back the final framebuffer — no specific
    /// pattern assertion (mode geometry would tie the test to the
    /// shader), just "ran clean and produced non-zero output".
    #[test]
    fn waveform_dispatch_runs_for_every_md2_mode() {
        for mode in 0..=7 {
            let mut r = pollster::block_on(MilkRenderer::new(RenderConfig::default())).unwrap();
            // Set a recognisable wave colour so the pass actually writes
            // something we can detect in the framebuffer.
            let mut s = RenderState::default();
            s.wave.mode = mode;
            s.wave.r = 1.0;
            s.wave.g = 0.5;
            s.wave.b = 0.0;
            s.wave.a = 1.0;
            s.wave.scale = 0.5;
            s.wave.thick = mode % 2 == 0;
            s.wave.additive = mode == 3;
            s.wave.dots = mode == 5;
            r.update_state(s);
            // Deterministic sine wave so the renderer has signal to draw.
            let samples: Vec<f32> = (0..NUM_WAVE_SAMPLES)
                .map(|i| (i as f32 * 0.05).sin() * 0.6)
                .collect();
            r.update_waveform_samples(&samples, 0.5);
            r.render().unwrap();
            let frame = r.read_render_texture().unwrap();
            assert!(
                frame.iter().any(|&b| b != 0),
                "mode {} produced an all-zero framebuffer",
                mode
            );
        }
    }

    /// `update_waveform_samples` must always end up with exactly
    /// `NUM_WAVE_SAMPLES` entries (zero-padded if shorter) so the GPU
    /// storage upload size matches the pipeline expectation.
    #[test]
    fn waveform_samples_buffer_is_canonicalised() {
        use crate::waveform::NUM_WAVE_SAMPLES;
        let mut r = pollster::block_on(MilkRenderer::new(RenderConfig::default())).unwrap();
        r.update_waveform_samples(&[0.5, -0.5, 0.25], 0.1);
        assert_eq!(r.wave_samples().len(), NUM_WAVE_SAMPLES);
        // Padding tail is zero.
        assert!(r.wave_samples().iter().skip(3).all(|&v| v.abs() < 1e-6));
    }

    /// Smoothing applied to the sample buffer attenuates spike-y input.
    /// Drives the smoothing path that runs before each GPU upload.
    #[test]
    fn waveform_smoothing_path_attenuates() {
        let mut r = pollster::block_on(MilkRenderer::new(RenderConfig::default())).unwrap();
        let mut s = RenderState::default();
        s.wave.smoothing = 0.9;
        r.update_state(s);
        let spiky: Vec<f32> = (0..NUM_WAVE_SAMPLES)
            .map(|i| if i % 2 == 0 { 1.0 } else { -1.0 })
            .collect();
        r.update_waveform_samples(&spiky, 0.0);
        let max = r.wave_samples().iter().cloned().fold(f32::MIN, f32::max);
        let min = r.wave_samples().iter().cloned().fold(f32::MAX, f32::min);
        assert!(
            (max - min) < 1.5,
            "smoothing did not attenuate spiky input (peak-to-peak {})",
            max - min
        );
    }

    /// `additive` and `dots` flags propagate through `RenderState` and
    /// drive the pipeline-selection branch in `render`. The visible
    /// test surface is "render() succeeds for every combination" — the
    /// exact pixel output is the shader's job, covered by other tests.
    #[test]
    fn waveform_blend_and_dots_flags_dispatch() {
        for &(thick, dots, additive) in &[
            (false, false, false),
            (true, false, false),
            (false, true, false),
            (false, false, true),
            (true, true, true),
        ] {
            let mut r = pollster::block_on(MilkRenderer::new(RenderConfig::default())).unwrap();
            let mut s = RenderState::default();
            s.wave.mode = 0;
            s.wave.thick = thick;
            s.wave.dots = dots;
            s.wave.additive = additive;
            r.update_state(s);
            r.update_waveform_samples(&[0.3_f32; NUM_WAVE_SAMPLES], 0.4);
            r.render().expect("render must succeed for any flag combo");
        }
    }

    /// `b_mod_wave_alpha_by_volume` should make the wave dim at silence
    /// and brighter at high volume. We exercise both ends and check the
    /// renderer doesn't reject either — the geometry/colour test for the
    /// envelope itself is the `build_uniforms_mod_alpha_*` unit test.
    #[test]
    fn waveform_mod_alpha_by_volume_drives_dispatch() {
        let mut r = pollster::block_on(MilkRenderer::new(RenderConfig::default())).unwrap();
        let mut s = RenderState::default();
        s.wave.mod_alpha_by_volume = true;
        s.wave.mod_alpha_start = 0.0;
        s.wave.mod_alpha_end = 1.0;
        r.update_state(s);

        r.update_waveform_samples(&[0.2_f32; NUM_WAVE_SAMPLES], 0.0);
        r.render().unwrap();
        r.update_waveform_samples(&[0.2_f32; NUM_WAVE_SAMPLES], 1.0);
        r.render().unwrap();
    }

    #[test]
    fn rendering_is_deterministic_within_session() {
        // Two independent renderer instances driven through the same warp UV
        // sequence must produce the same final framebuffer. We seed the warp
        // UVs by hand (no audio, no presets) so the test does not depend on
        // any other engine state.
        let make = || {
            let mut r = pollster::block_on(MilkRenderer::new(RenderConfig::default())).unwrap();
            for frame in 0..5 {
                let mesh = r.warp_mesh();
                // Identity warp + slight time-dependent shift so consecutive
                // frames diverge from a single "all-zeroes" output.
                let verts: Vec<crate::warp_pipeline::WarpVertex> = mesh
                    .vertices
                    .iter()
                    .map(|v| {
                        let shift = (frame as f32) * 0.01;
                        crate::warp_pipeline::WarpVertex {
                            pos_clip: v.pos_clip,
                            uv_warp: [v.uv_orig[0] + shift, v.uv_orig[1] + shift],
                        }
                    })
                    .collect();
                r.update_warp_vertices(&verts);
                r.render().unwrap();
            }
            r.read_render_texture().unwrap()
        };

        let a = make();
        let b = make();
        assert_eq!(a.len(), b.len(), "readback length mismatch");
        assert_eq!(a, b, "non-deterministic rendering: byte-level mismatch");
        // Sanity: not all zeroes — confirms the test actually exercised the
        // pipeline rather than reading an untouched texture.
        assert!(
            a.iter().any(|&b| b != 0),
            "framebuffer is all-zero, test did not actually render"
        );
    }

    // -----------------------------------------------------------------
    // Borders + motion vectors dispatched end-to-end
    // -----------------------------------------------------------------

    /// `RenderState::default` has zero alpha on both border rings and
    /// the motion-vector grid, so the renderer must take the no-op
    /// path: zero draw calls, zero segments.
    #[test]
    fn borders_and_motion_vectors_default_to_noop() {
        let mut r = pollster::block_on(MilkRenderer::new(RenderConfig::default())).unwrap();
        r.update_state(RenderState::default());
        r.render().unwrap();
        assert_eq!(r.border_batch_count(), 0);
        assert_eq!(r.motion_vector_segment_count(), 0);
    }

    /// Enabling either ring should produce exactly one batch; enabling
    /// both must produce two. Mirrors the typical preset case of "outer
    /// border off, inner on" → one ring drawn.
    #[test]
    fn borders_batch_count_tracks_visibility() {
        let mut r = pollster::block_on(MilkRenderer::new(RenderConfig::default())).unwrap();
        let mut s = RenderState::default();
        s.borders.outer_size = 0.02;
        s.borders.outer_color = [1.0, 0.5, 0.0, 1.0];
        r.update_state(s);
        r.render().unwrap();
        assert_eq!(r.border_batch_count(), 1);

        s.borders.inner_size = 0.01;
        s.borders.inner_color = [0.2, 0.4, 0.6, 0.8];
        r.update_state(s);
        r.render().unwrap();
        assert_eq!(r.border_batch_count(), 2);
    }

    /// Motion-vector grid produces `nx * ny` segments when enabled and
    /// clamps at the MD2 cap of 64×48 regardless of the requested size.
    #[test]
    fn motion_vector_segments_grid_and_cap() {
        let mut r = pollster::block_on(MilkRenderer::new(RenderConfig::default())).unwrap();
        let mut s = RenderState::default();
        s.motion_vectors.grid_x = 8;
        s.motion_vectors.grid_y = 6;
        s.motion_vectors.color = [1.0, 1.0, 1.0, 0.7];
        r.update_state(s);
        r.render().unwrap();
        assert_eq!(r.motion_vector_segment_count(), 8 * 6);

        // Way past the MD2 cap: must clamp to 64 × 48.
        s.motion_vectors.grid_x = 200;
        s.motion_vectors.grid_y = 100;
        r.update_state(s);
        r.render().unwrap();
        assert_eq!(r.motion_vector_segment_count(), 64 * 48);
    }

    /// Setting either alpha to zero on a previously visible pass must
    /// flip the renderer back to the no-op path (no batches / no
    /// segments). Per-frame eqs in MD2 can toggle these mid-preset.
    #[test]
    fn alpha_zero_disables_pass_again() {
        let mut r = pollster::block_on(MilkRenderer::new(RenderConfig::default())).unwrap();
        let mut s = RenderState::default();
        s.borders.outer_size = 0.02;
        s.borders.outer_color = [1.0, 0.0, 0.0, 1.0];
        s.motion_vectors.grid_x = 4;
        s.motion_vectors.grid_y = 3;
        s.motion_vectors.color = [1.0, 1.0, 1.0, 1.0];
        r.update_state(s);
        r.render().unwrap();
        assert_eq!(r.border_batch_count(), 1);
        assert_eq!(r.motion_vector_segment_count(), 12);

        s.borders.outer_color[3] = 0.0;
        s.motion_vectors.color[3] = 0.0;
        r.update_state(s);
        r.render().unwrap();
        assert_eq!(r.border_batch_count(), 0);
        assert_eq!(r.motion_vector_segment_count(), 0);
    }
}