@bloomengine/engine 0.3.1

package/native/shared/src/audio.rs

@@ -0,0 +1,363 @@
+use crate::handles::HandleRegistry;
+
+/// A loaded sound effect (PCM samples).
+pub struct SoundData {
+    pub samples: Vec<f32>,
+    pub sample_rate: u32,
+    pub channels: u16,
+}
+
+/// A currently playing sound instance.
+struct PlayingSound {
+    data_handle: f64,
+    position: usize,
+    volume: f32,
+    playing: bool,
+    // Spatial audio
+    spatial: bool,
+    source_x: f32,
+    source_y: f32,
+    source_z: f32,
+}
+
+/// Music data (fully decoded for simplicity).
+pub struct MusicData {
+    pub samples: Vec<f32>,
+    pub sample_rate: u32,
+    pub channels: u16,
+    pub position: usize,
+    pub playing: bool,
+    pub volume: f32,
+    pub looping: bool,
+}
+
+/// Platform-agnostic audio mixer.
+pub struct AudioMixer {
+    pub sounds: HandleRegistry<SoundData>,
+    playing: Vec<PlayingSound>,
+    pub master_volume: f32,
+    sound_volumes: Vec<(f64, f32)>,
+    pub music: HandleRegistry<MusicData>,
+    // Spatial audio listener
+    pub listener_x: f32,
+    pub listener_y: f32,
+    pub listener_z: f32,
+    pub listener_forward_x: f32,
+    pub listener_forward_y: f32,
+    pub listener_forward_z: f32,
+}
+
+impl AudioMixer {
+    pub fn new() -> Self {
+        Self {
+            sounds: HandleRegistry::new(),
+            playing: Vec::new(),
+            master_volume: 1.0,
+            sound_volumes: Vec::new(),
+            music: HandleRegistry::new(),
+            listener_x: 0.0,
+            listener_y: 0.0,
+            listener_z: 0.0,
+            listener_forward_x: 0.0,
+            listener_forward_y: 0.0,
+            listener_forward_z: -1.0,
+        }
+    }
+
+    pub fn load_sound(&mut self, data: SoundData) -> f64 {
+        self.sounds.alloc(data)
+    }
+
+    pub fn play_sound(&mut self, handle: f64) {
+        self.playing.push(PlayingSound {
+            data_handle: handle,
+            position: 0,
+            volume: self.get_sound_volume(handle),
+            playing: true,
+            spatial: false,
+            source_x: 0.0, source_y: 0.0, source_z: 0.0,
+        });
+    }
+
+    pub fn play_sound_3d(&mut self, handle: f64, x: f32, y: f32, z: f32) {
+        self.playing.push(PlayingSound {
+            data_handle: handle,
+            position: 0,
+            volume: self.get_sound_volume(handle),
+            playing: true,
+            spatial: true,
+            source_x: x, source_y: y, source_z: z,
+        });
+    }
+
+    pub fn set_listener_position(&mut self, x: f32, y: f32, z: f32, fx: f32, fy: f32, fz: f32) {
+        self.listener_x = x;
+        self.listener_y = y;
+        self.listener_z = z;
+        let len = (fx*fx + fy*fy + fz*fz).sqrt();
+        if len > 0.0 {
+            self.listener_forward_x = fx / len;
+            self.listener_forward_y = fy / len;
+            self.listener_forward_z = fz / len;
+        }
+    }
+
+    pub fn stop_sound(&mut self, handle: f64) {
+        self.playing.retain(|p| p.data_handle != handle);
+    }
+
+    pub fn set_sound_volume(&mut self, handle: f64, volume: f32) {
+        for entry in &mut self.sound_volumes {
+            if entry.0 == handle {
+                entry.1 = volume;
+                for p in &mut self.playing {
+                    if p.data_handle == handle { p.volume = volume; }
+                }
+                return;
+            }
+        }
+        self.sound_volumes.push((handle, volume));
+    }
+
+    fn get_sound_volume(&self, handle: f64) -> f32 {
+        for entry in &self.sound_volumes {
+            if entry.0 == handle { return entry.1; }
+        }
+        1.0
+    }
+
+    // Music functions
+
+    pub fn load_music(&mut self, data: SoundData) -> f64 {
+        self.music.alloc(MusicData {
+            samples: data.samples,
+            sample_rate: data.sample_rate,
+            channels: data.channels,
+            position: 0,
+            playing: false,
+            volume: 1.0,
+            looping: true,
+        })
+    }
+
+    pub fn play_music(&mut self, handle: f64) {
+        if let Some(m) = self.music.get_mut(handle) {
+            m.position = 0;
+            m.playing = true;
+        }
+    }
+
+    pub fn stop_music(&mut self, handle: f64) {
+        if let Some(m) = self.music.get_mut(handle) {
+            m.playing = false;
+            m.position = 0;
+        }
+    }
+
+    pub fn set_music_volume(&mut self, handle: f64, volume: f32) {
+        if let Some(m) = self.music.get_mut(handle) {
+            m.volume = volume;
+        }
+    }
+
+    pub fn is_music_playing(&self, handle: f64) -> bool {
+        self.music.get(handle).map(|m| m.playing).unwrap_or(false)
+    }
+
+    pub fn update_music_stream(&mut self, _handle: f64) {
+        // No-op: we decode everything upfront. This exists for API compatibility.
+    }
+
+    /// Mix all playing sounds and music into the output buffer.
+    pub fn mix_output(&mut self, output: &mut [f32]) {
+        for sample in output.iter_mut() {
+            *sample = 0.0;
+        }
+
+        // Spatial audio: compute listener-relative parameters once
+        let lx = self.listener_x;
+        let ly = self.listener_y;
+        let lz = self.listener_z;
+        let lfx = self.listener_forward_x;
+        let _lfy = self.listener_forward_y;  // unused — listener "right" math projects out the Y component
+        let lfz = self.listener_forward_z;
+        // Listener right vector (cross product of forward and up=[0,1,0])
+        let lrx = lfz;
+        let lrz = -lfx;
+        let lr_len = (lrx * lrx + lrz * lrz).sqrt().max(0.001);
+
+        // Mix sound effects
+        self.playing.retain_mut(|p| {
+            if !p.playing { return false; }
+            let sound = match self.sounds.get(p.data_handle) {
+                Some(s) => s,
+                None => return false,
+            };
+
+            // Compute spatial gain and pan
+            let (gain_l, gain_r) = if p.spatial {
+                let dx = p.source_x - lx;
+                let dy = p.source_y - ly;
+                let dz = p.source_z - lz;
+                let dist = (dx*dx + dy*dy + dz*dz).sqrt().max(0.1);
+                // Distance attenuation: 1/distance, clamped
+                let attenuation = (1.0 / dist).min(1.0);
+                // Pan: dot product of source direction with listener right
+                let pan = ((dx * lrx + dz * lrz) / (dist * lr_len)).clamp(-1.0, 1.0);
+                let left = attenuation * (1.0 - pan) * 0.5;
+                let right = attenuation * (1.0 + pan) * 0.5;
+                (left, right)
+            } else {
+                (1.0, 1.0)
+            };
+
+            let base_vol = p.volume * self.master_volume;
+            let vol_l = base_vol * gain_l;
+            let vol_r = base_vol * gain_r;
+            let mut i = 0;
+            while i < output.len() && p.position < sound.samples.len() {
+                if sound.channels == 1 {
+                    let sample = sound.samples[p.position];
+                    output[i] += sample * vol_l;
+                    if i + 1 < output.len() { output[i + 1] += sample * vol_r; }
+                    p.position += 1;
+                    i += 2;
+                } else {
+                    // For stereo sources, apply gain to each channel
+                    output[i] += sound.samples[p.position] * vol_l;
+                    p.position += 1;
+                    if i + 1 < output.len() && p.position < sound.samples.len() {
+                        output[i + 1] += sound.samples[p.position] * vol_r;
+                        p.position += 1;
+                    }
+                    i += 2;
+                }
+            }
+            p.position < sound.samples.len()
+        });
+
+        // Mix music (iterate all music handles)
+        // We need to collect handles first to avoid borrow issues
+        let handles: Vec<f64> = {
+            let mut h = Vec::new();
+            // HandleRegistry stores items as Vec<Option<T>>, handles are 1-based
+            for i in 0..100 {
+                let handle = (i + 1) as f64;
+                if self.music.get(handle).is_some() {
+                    h.push(handle);
+                } else if i > 10 && h.is_empty() {
+                    break;
+                }
+            }
+            h
+        };
+
+        for handle in handles {
+            if let Some(m) = self.music.get_mut(handle) {
+                if !m.playing { continue; }
+                let vol = m.volume * self.master_volume;
+                let mut i = 0;
+                while i < output.len() && m.position < m.samples.len() {
+                    if m.channels == 1 {
+                        let sample = m.samples[m.position] * vol;
+                        output[i] += sample;
+                        if i + 1 < output.len() { output[i + 1] += sample; }
+                        m.position += 1;
+                        i += 2;
+                    } else {
+                        output[i] += m.samples[m.position] * vol;
+                        m.position += 1;
+                        i += 1;
+                    }
+                }
+                if m.position >= m.samples.len() {
+                    if m.looping {
+                        m.position = 0;
+                    } else {
+                        m.playing = false;
+                    }
+                }
+            }
+        }
+    }
+}
+
+/// Parse a WAV file into SoundData.
+pub fn parse_wav(data: &[u8]) -> Option<SoundData> {
+    if data.len() < 44 { return None; }
+    if &data[0..4] != b"RIFF" || &data[8..12] != b"WAVE" { return None; }
+
+    let channels = u16::from_le_bytes([data[22], data[23]]);
+    let sample_rate = u32::from_le_bytes([data[24], data[25], data[26], data[27]]);
+    let bits_per_sample = u16::from_le_bytes([data[34], data[35]]);
+
+    let mut offset = 36;
+    while offset + 8 < data.len() {
+        let chunk_id = &data[offset..offset + 4];
+        let chunk_size = u32::from_le_bytes([
+            data[offset + 4], data[offset + 5], data[offset + 6], data[offset + 7],
+        ]) as usize;
+
+        if chunk_id == b"data" {
+            let pcm_data = &data[offset + 8..std::cmp::min(offset + 8 + chunk_size, data.len())];
+            let samples = match bits_per_sample {
+                16 => pcm_data.chunks_exact(2)
+                    .map(|chunk| i16::from_le_bytes([chunk[0], chunk[1]]) as f32 / 32768.0)
+                    .collect(),
+                8 => pcm_data.iter()
+                    .map(|&b| (b as f32 - 128.0) / 128.0)
+                    .collect(),
+                _ => return None,
+            };
+            return Some(SoundData { samples, sample_rate, channels });
+        }
+        offset += 8 + chunk_size;
+    }
+    None
+}
+
+/// Parse an MP3 file into SoundData.
+#[cfg(feature = "mp3")]
+pub fn parse_mp3(data: &[u8]) -> Option<SoundData> {
+    let mut decoder = minimp3::Decoder::new(std::io::Cursor::new(data));
+    let mut samples = Vec::new();
+    let mut sample_rate = 0u32;
+    let mut channels = 0u16;
+
+    loop {
+        match decoder.next_frame() {
+            Ok(frame) => {
+                if sample_rate == 0 {
+                    sample_rate = frame.sample_rate as u32;
+                    channels = frame.channels as u16;
+                }
+                for &s in &frame.data {
+                    samples.push(s as f32 / 32768.0);
+                }
+            }
+            Err(minimp3::Error::Eof) => break,
+            Err(_) => return None,
+        }
+    }
+
+    if samples.is_empty() { return None; }
+    Some(SoundData { samples, sample_rate, channels })
+}
+
+/// Parse an OGG Vorbis file into SoundData.
+pub fn parse_ogg(data: &[u8]) -> Option<SoundData> {
+    let cursor = std::io::Cursor::new(data);
+    let mut reader = lewton::inside_ogg::OggStreamReader::new(cursor).ok()?;
+    let sample_rate = reader.ident_hdr.audio_sample_rate;
+    let channels = reader.ident_hdr.audio_channels as u16;
+    let mut samples = Vec::new();
+
+    while let Ok(Some(packet)) = reader.read_dec_packet_itl() {
+        for &sample in &packet {
+            samples.push(sample as f32 / 32768.0);
+        }
+    }
+
+    if samples.is_empty() { return None; }
+    Some(SoundData { samples, sample_rate, channels })
+}

package/native/shared/src/custom_shaders.rs

@@ -0,0 +1,104 @@
+//! Custom WGSL shaders for Pascal Editor effects.
+//!
+//! These are hand-ported equivalents of the Three.js TSL (Texture Shading Language)
+//! node materials used in the Pascal Editor:
+//! - Wall cutaway dot pattern
+//! - Zone gradient
+//! - Item preview shimmer
+//!
+//! In the browser, these are defined as JavaScript function calls (TSL nodes) that
+//! compile to WGSL at runtime. Since we compile natively, we write the WGSL directly.
+
+/// Wall cutaway dot pattern — shows dots that fade with height when a wall
+/// is in "cutaway" mode. Replaces the TSL `Fn(() => { ... fract ... step ... })`.
+pub const WALL_CUTAWAY_SHADER: &str = "
+struct CutawayParams {
+    dot_scale: vec4<f32>,      // [scale, dot_size, fade_height, opacity]
+    base_color: vec4<f32>,     // rgba
+};
+
+@group(0) @binding(0) var<uniform> params: CutawayParams;
+
+struct VertexOutput {
+    @builtin(position) clip_position: vec4<f32>,
+    @location(0) local_pos: vec3<f32>,
+    @location(1) color: vec4<f32>,
+};
+
+@fragment
+fn fs_wall_cutaway(in: VertexOutput) -> @location(0) vec4<f32> {
+    let scale = params.dot_scale.x;
+    let dot_size = params.dot_scale.y;
+    let fade_height = params.dot_scale.z;
+
+    // Create repeating dot grid
+    let uv = vec2<f32>(in.local_pos.x, in.local_pos.y) / scale;
+    let grid_uv = fract(uv);
+    let dist = length(grid_uv - vec2<f32>(0.5));
+    let dots = step(dist, dot_size * 0.5);
+
+    // Vertical fade (transparent near bottom, opaque at top)
+    let y_fade = 1.0 - smoothstep(0.0, fade_height, in.local_pos.y);
+
+    let alpha = dots * y_fade * params.dot_scale.w;
+    if (alpha < 0.01) { discard; }
+
+    return vec4<f32>(params.base_color.rgb * in.color.rgb, alpha);
+}
+";
+
+/// Zone gradient — vertical gradient for zone visualization walls.
+/// Replaces the TSL `uv().y → mul(opacity)` with uniform.
+pub const ZONE_GRADIENT_SHADER: &str = "
+struct ZoneParams {
+    base_color: vec4<f32>,    // rgba
+    opacity: vec4<f32>,       // [max_opacity, 0, 0, 0]
+};
+
+@group(0) @binding(0) var<uniform> zone_params: ZoneParams;
+
+struct VertexOutput {
+    @builtin(position) clip_position: vec4<f32>,
+    @location(0) uv: vec2<f32>,
+    @location(1) color: vec4<f32>,
+};
+
+@fragment
+fn fs_zone_gradient(in: VertexOutput) -> @location(0) vec4<f32> {
+    // Gradient: fully opaque at bottom, transparent at top
+    let gradient_t = in.uv.y;
+    let alpha = zone_params.opacity.x * (1.0 - gradient_t) * 0.6;
+    return vec4<f32>(zone_params.base_color.rgb, alpha);
+}
+";
+
+/// Item preview shimmer — animated shimmer effect for item placement preview.
+/// Replaces the TSL `positionLocal.y + time → fract → smoothstep`.
+pub const PREVIEW_SHIMMER_SHADER: &str = "
+struct ShimmerParams {
+    time: vec4<f32>,          // [time, speed, 0, 0]
+    base_color: vec4<f32>,    // rgba
+};
+
+@group(0) @binding(0) var<uniform> shimmer_params: ShimmerParams;
+
+struct VertexOutput {
+    @builtin(position) clip_position: vec4<f32>,
+    @location(0) local_pos: vec3<f32>,
+    @location(1) color: vec4<f32>,
+};
+
+@fragment
+fn fs_preview_shimmer(in: VertexOutput) -> @location(0) vec4<f32> {
+    let time = shimmer_params.time.x;
+    let speed = shimmer_params.time.y;
+
+    // Scrolling shimmer band
+    let shimmer_y = fract((in.local_pos.y + time * speed) * 10.0);
+    let shimmer = smoothstep(0.0, 0.1, shimmer_y) * smoothstep(0.3, 0.2, shimmer_y);
+
+    let base = shimmer_params.base_color;
+    let brightness = 1.0 + shimmer * 0.3;
+    return vec4<f32>(base.rgb * brightness, base.a * 0.7);
+}
+";

package/native/shared/src/drs.rs

@@ -0,0 +1,211 @@
+//! Dynamic resolution scaling (DRS) — self-tunes the renderer's
+//! `render_scale` to track a target framerate. Lives outside the
+//! renderer so it can read frame-time from the engine without
+//! threading a timing source down.
+//!
+//! Algorithm sketch:
+//! - Smooth frame time with an EMA (~10-frame window).
+//! - After a cooldown, step `render_scale` down one rung when EMA
+//!   exceeds target × 1.10, up one rung when EMA falls below
+//!   target × 0.80. Asymmetric thresholds — humans tolerate blur
+//!   better than stutter, so we drop quickly and recover slowly.
+//! - 6-rung ladder spaced ~√2 apart: 0.50 → 0.58 → 0.67 → 0.75 →
+//!   0.85 → 1.00. Keeps step size proportional to fragment cost.
+//! - Cooldown of 30 frames between any two steps prevents thrashing.
+
+use crate::renderer::Renderer;
+
+/// Discrete render-scale rungs DRS can choose from. Spaced so each
+/// step is roughly a √2 change in fragment-shader cost.
+const STEPS: &[f32] = &[0.50, 0.58, 0.67, 0.75, 0.85, 1.00];
+
+/// EMA smoothing factor — α=0.1 ≈ 10-frame effective window.
+/// Responsive enough to catch a sustained spike, slow enough to
+/// ignore single-frame outliers.
+const EMA_ALPHA: f32 = 0.1;
+
+/// Frames between any two scale steps. At 60 fps this is 0.5 s,
+/// long enough for the EMA to reflect the post-step frame time.
+const COOLDOWN_FRAMES: u32 = 30;
+
+/// Step *down* (cheaper) when EMA exceeds target × this.
+const HYSTERESIS_DOWN: f32 = 1.10;
+/// Step *up* (sharper) only when EMA falls below target × this.
+/// Tighter than HYSTERESIS_DOWN — blur is preferable to stutter.
+const HYSTERESIS_UP: f32 = 0.80;
+
+pub struct DrsController {
+    pub enabled: bool,
+    /// Per-frame target in milliseconds (1000 / target_hz).
+    pub target_frame_ms: f32,
+    ema_ms: f32,
+    frames_since_step: u32,
+    /// Index into `STEPS`. Starts at the top so DRS only ever cuts
+    /// from the user's chosen baseline downward — once enabled it
+    /// will climb back as headroom appears.
+    idx: usize,
+}
+
+impl DrsController {
+    pub fn new() -> Self {
+        Self {
+            enabled: false,
+            target_frame_ms: 1000.0 / 60.0,
+            ema_ms: 0.0,
+            frames_since_step: 0,
+            idx: STEPS.len() - 1, // 1.0 — start at native, step down as needed
+        }
+    }
+
+    /// Enable DRS targeting the given refresh rate in Hz. Snaps the
+    /// internal index to whichever rung is closest to the renderer's
+    /// current `render_scale` so the first step doesn't overshoot.
+    pub fn enable(&mut self, target_hz: f32, current_scale: f32) {
+        self.enabled = true;
+        self.target_frame_ms = 1000.0 / target_hz.max(1.0);
+        self.ema_ms = 0.0;
+        self.frames_since_step = 0;
+        self.idx = closest_step_idx(current_scale);
+    }
+
+    pub fn disable(&mut self) {
+        self.enabled = false;
+    }
+
+    /// Called once per frame from `EngineState::begin_frame` after
+    /// `delta_time` is updated. `dt_seconds` is wall-clock frame time.
+    pub fn tick(&mut self, dt_seconds: f64, renderer: &mut Renderer) {
+        if !self.enabled {
+            return;
+        }
+
+        let frame_ms = (dt_seconds * 1000.0) as f32;
+        // EMA bootstrap — first frame after enable, seed the buffer
+        // with the observed value so we don't spend 10 frames climbing
+        // from 0 toward the steady state.
+        if self.ema_ms == 0.0 {
+            self.ema_ms = frame_ms;
+        } else {
+            self.ema_ms += EMA_ALPHA * (frame_ms - self.ema_ms);
+        }
+
+        self.frames_since_step = self.frames_since_step.saturating_add(1);
+        if self.frames_since_step < COOLDOWN_FRAMES {
+            return;
+        }
+
+        let target = self.target_frame_ms;
+        if self.ema_ms > target * HYSTERESIS_DOWN && self.idx > 0 {
+            self.idx -= 1;
+            renderer.set_render_scale(STEPS[self.idx]);
+            self.frames_since_step = 0;
+        } else if self.ema_ms < target * HYSTERESIS_UP && self.idx + 1 < STEPS.len() {
+            self.idx += 1;
+            renderer.set_render_scale(STEPS[self.idx]);
+            self.frames_since_step = 0;
+        }
+    }
+
+    pub fn current_scale(&self) -> f32 { STEPS[self.idx] }
+}
+
+impl Default for DrsController {
+    fn default() -> Self { Self::new() }
+}
+
+fn closest_step_idx(scale: f32) -> usize {
+    let mut best = 0usize;
+    let mut best_d = (STEPS[0] - scale).abs();
+    for (i, s) in STEPS.iter().enumerate().skip(1) {
+        let d = (s - scale).abs();
+        if d < best_d {
+            best_d = d;
+            best = i;
+        }
+    }
+    best
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn closest_step_idx_picks_nearest_rung() {
+        // STEPS = [0.50, 0.58, 0.67, 0.75, 0.85, 1.00]
+        assert_eq!(closest_step_idx(0.50), 0);
+        assert_eq!(closest_step_idx(0.53), 0); // closer to 0.50 (Δ0.03) than 0.58 (Δ0.05)
+        assert_eq!(closest_step_idx(0.55), 1); // closer to 0.58 (Δ0.03) than 0.50 (Δ0.05)
+        assert_eq!(closest_step_idx(0.70), 2); // closer to 0.67 (Δ0.03) than 0.75 (Δ0.05)
+        assert_eq!(closest_step_idx(1.00), 5);
+        assert_eq!(closest_step_idx(2.00), 5); // clamped at top
+        assert_eq!(closest_step_idx(0.0), 0);  // clamped at bottom
+    }
+
+    #[test]
+    fn disabled_controller_never_steps() {
+        let mut drs = DrsController::new();
+        // Don't enable. Even with a huge frame time the controller
+        // should be a no-op (no renderer reference passed: skip via
+        // early return — exercised by reading enabled state).
+        for _ in 0..100 {
+            // Mimic: tick() early-returns when !enabled. We test by
+            // confirming idx hasn't moved off its initial top rung.
+            assert!(!drs.enabled);
+        }
+        assert_eq!(drs.idx, STEPS.len() - 1);
+    }
+
+    #[test]
+    fn enable_seeds_index_to_nearest_rung() {
+        let mut drs = DrsController::new();
+        drs.enable(60.0, 0.75);
+        assert_eq!(drs.idx, 3); // 0.75 is rung 3
+        assert_eq!(drs.current_scale(), 0.75);
+        assert!(drs.enabled);
+        assert!((drs.target_frame_ms - 1000.0 / 60.0).abs() < 0.001);
+    }
+
+    /// Synthetic frame-time trace: induce a 33 ms spike on a 60 fps
+    /// (16.67 ms) target and confirm the controller steps down,
+    /// then steps back up when frame time recovers.
+    #[test]
+    fn step_down_on_spike_recover_on_idle() {
+        let mut drs = DrsController::new();
+        drs.enable(60.0, 1.0);
+        let start_idx = drs.idx;
+
+        // Simulate the EMA + cooldown logic *without* a renderer by
+        // inlining the same updates against a local idx tracker.
+        let target = drs.target_frame_ms;
+        let mut idx = drs.idx;
+        let mut ema = 0.0f32;
+        let mut cooldown = 0u32;
+
+        let advance = |ms: f32, ema: &mut f32, idx: &mut usize, cooldown: &mut u32| {
+            if *ema == 0.0 { *ema = ms; } else { *ema += EMA_ALPHA * (ms - *ema); }
+            *cooldown = cooldown.saturating_add(1);
+            if *cooldown < COOLDOWN_FRAMES { return; }
+            if *ema > target * HYSTERESIS_DOWN && *idx > 0 {
+                *idx -= 1; *cooldown = 0;
+            } else if *ema < target * HYSTERESIS_UP && *idx + 1 < STEPS.len() {
+                *idx += 1; *cooldown = 0;
+            }
+        };
+
+        // 200 frames at 33ms (double target) should drop the rung
+        // at least once.
+        for _ in 0..200 {
+            advance(33.0, &mut ema, &mut idx, &mut cooldown);
+        }
+        assert!(idx < start_idx, "expected step-down, idx={idx}");
+
+        // 400 frames at 8ms (well under HYSTERESIS_UP * target = 13.3ms)
+        // should recover at least one rung.
+        let after_spike = idx;
+        for _ in 0..400 {
+            advance(8.0, &mut ema, &mut idx, &mut cooldown);
+        }
+        assert!(idx > after_spike, "expected step-up, idx={idx}");
+    }
+}