Merge branch 'wip/2025-08-09'

# Please enter a commit message to explain why this merge is necessary,
# especially if it merges an updated upstream into a topic branch.
#
# Lines starting with '#' will be ignored, and an empty message aborts
# the commit.

Author: rgilks

crates/app-core/src/music.rs

@@ -2,6 +2,7 @@ use glam::Vec3;
 use rand::prelude::*;
 use std::time::Duration;
 
+/// Basic oscillator shape used by synths in both native and web front-ends.
 #[derive(Clone, Copy, Debug)]
 pub enum Waveform {
     Sine,
@@ -10,13 +11,15 @@ pub enum Waveform {
     Triangle,
 }
 
+/// Static configuration for a voice: color, waveform and initial position.
 #[derive(Clone, Debug)]
 pub struct VoiceConfig {
     pub color_rgb: [f32; 3],
     pub waveform: Waveform,
     pub base_position: Vec3,
 }
 
+/// Scheduled note event produced by the music engine.
 #[derive(Clone, Debug, Default)]
 pub struct NoteEvent {
     pub voice_index: usize,
@@ -26,12 +29,14 @@ pub struct NoteEvent {
     pub duration_sec: f32,
 }
 
+/// Mutable runtime state per voice.
 #[derive(Clone, Debug)]
 pub struct VoiceState {
     pub position: Vec3,
     pub muted: bool,
 }
 
+/// Global engine parameters controlling tempo and scale.
 #[derive(Clone, Debug)]
 pub struct EngineParams {
     pub bpm: f32,
@@ -47,8 +52,10 @@ impl Default for EngineParams {
     }
 }
 
+/// Default five-note scale centered around middle C.
 pub const C_MAJOR_PENTATONIC: &[i32] = &[0, 2, 4, 7, 9, 12];
 
+/// Random generative scheduler producing `NoteEvent`s on an eighth-note grid.
 pub struct MusicEngine {
     pub voices: Vec<VoiceState>,
     pub configs: Vec<VoiceConfig>,
@@ -59,6 +66,7 @@ pub struct MusicEngine {
 }
 
 impl MusicEngine {
+    /// Construct a new engine with voices derived from the provided configs.
     pub fn new(configs: Vec<VoiceConfig>, params: EngineParams, seed: u64) -> Self {
         let voices = configs
             .iter()
@@ -86,35 +94,41 @@ impl MusicEngine {
         }
     }
 
+    /// Set beats-per-minute for the internal scheduler.
     pub fn set_bpm(&mut self, bpm: f32) {
         self.params.bpm = bpm;
     }
 
+    /// Toggle mute flag for a voice.
     pub fn toggle_mute(&mut self, voice_index: usize) {
         if let Some(v) = self.voices.get_mut(voice_index) {
             v.muted = !v.muted;
         }
     }
 
+    /// Explicitly set mute flag for a voice.
     pub fn set_voice_muted(&mut self, voice_index: usize, muted: bool) {
         if let Some(v) = self.voices.get_mut(voice_index) {
             v.muted = muted;
         }
     }
 
+    /// Update the engine-space position of a voice.
     pub fn set_voice_position(&mut self, voice_index: usize, pos: Vec3) {
         if let Some(v) = self.voices.get_mut(voice_index) {
             v.position = pos;
         }
     }
 
+    /// Reseed the per-voice RNG. If `seed` is None, a new random seed is chosen.
     pub fn reseed_voice(&mut self, voice_index: usize, seed: Option<u64>) {
         if let Some(r) = self.rngs.get_mut(voice_index) {
             let new_seed = seed.unwrap_or_else(|| r.gen());
             *r = StdRng::seed_from_u64(new_seed);
         }
     }
 
+    /// Solo a voice. Toggling solo on the same voice clears solo mode.
     pub fn toggle_solo(&mut self, voice_index: usize) {
         match self.solo_index {
             Some(idx) if idx == voice_index => {
@@ -133,6 +147,7 @@ impl MusicEngine {
         }
     }
 
+    /// Advance the scheduler by `dt`, pushing any newly scheduled `NoteEvent`s into `out_events`.
     pub fn tick(&mut self, dt: Duration, now_sec: f64, out_events: &mut Vec<NoteEvent>) {
         let seconds_per_beat = 60.0 / self.params.bpm as f64;
         self.beat_accum += dt.as_secs_f64();
@@ -143,32 +158,21 @@ impl MusicEngine {
         }
     }
 
+    /// Schedule a single grid step for all voices.
     fn schedule_step(&mut self, now_sec: f64, out_events: &mut Vec<NoteEvent>) {
         for (i, voice) in self.voices.iter().enumerate() {
             if voice.muted {
                 continue;
             }
-            // Probability to trigger per eighth note varies per voice
-            let prob = match i {
-                0 => 0.4,
-                1 => 0.6,
-                _ => 0.3,
-            };
-            if self.rngs[i].gen::<f32>() < prob {
-                let degree = *self.params.scale.choose(&mut self.rngs[i]).unwrap_or(&0);
-                let octave = match i {
-                    0 => -1,
-                    1 => 0,
-                    _ => 1,
-                };
+            let prob = MusicEngine::voice_trigger_probability(i);
+            let rng = &mut self.rngs[i];
+            if rng.gen::<f32>() < prob {
+                let degree = *self.params.scale.choose(rng).unwrap_or(&0);
+                let octave = MusicEngine::voice_octave_offset(i);
                 let midi = 60 + degree + octave * 12; // around middle C
                 let freq = midi_to_hz(midi as f32);
-                let vel = 0.4 + self.rngs[i].gen::<f32>() * 0.6;
-                let dur = match i {
-                    0 => 0.4,
-                    1 => 0.25,
-                    _ => 0.6,
-                } + self.rngs[i].gen::<f32>() * 0.2;
+                let vel = 0.4 + rng.gen::<f32>() * 0.6;
+                let dur = MusicEngine::voice_base_duration(i) + rng.gen::<f32>() * 0.2;
                 out_events.push(NoteEvent {
                     voice_index: i,
                     frequency_hz: freq,
@@ -179,13 +183,42 @@ impl MusicEngine {
             }
         }
     }
+
+    #[inline]
+    fn voice_trigger_probability(voice_index: usize) -> f32 {
+        match voice_index {
+            0 => 0.4,
+            1 => 0.6,
+            _ => 0.3,
+        }
+    }
+
+    #[inline]
+    fn voice_octave_offset(voice_index: usize) -> i32 {
+        match voice_index {
+            0 => -1,
+            1 => 0,
+            _ => 1,
+        }
+    }
+
+    #[inline]
+    fn voice_base_duration(voice_index: usize) -> f32 {
+        match voice_index {
+            0 => 0.4,
+            1 => 0.25,
+            _ => 0.6,
+        }
+    }
 }
 
+/// Convert a MIDI note number to Hertz (A4=440 Hz).
 pub fn midi_to_hz(midi: f32) -> f32 {
     440.0 * (2.0_f32).powf((midi - 69.0) / 12.0)
 }
 
 #[cfg(test)]
+#[allow(dead_code)]
 mod tests {
     use super::*;
     use std::time::Duration;
@@ -195,6 +228,39 @@ mod tests {
     }
 
     #[test]
+    fn engine_initializes_from_configs() {
+        let configs = vec![
+            VoiceConfig {
+                color_rgb: [1.0, 0.0, 0.0],
+                waveform: Waveform::Sine,
+                base_position: Vec3::new(-1.0, 0.0, 0.0),
+            },
+            VoiceConfig {
+                color_rgb: [0.0, 1.0, 0.0],
+                waveform: Waveform::Saw,
+                base_position: Vec3::new(1.0, 0.0, 0.0),
+            },
+        ];
+        let params = EngineParams::default();
+        let engine = MusicEngine::new(configs.clone(), params, 42);
+        assert_eq!(engine.voices.len(), configs.len());
+        assert_eq!(engine.configs.len(), configs.len());
+        assert_eq!(engine.voices[0].position, configs[0].base_position);
+        assert_eq!(engine.voices[1].position, configs[1].base_position);
+    }
+
+    #[test]
+    fn set_voice_position_updates_state() {
+        let configs = vec![VoiceConfig {
+            color_rgb: [1.0, 0.0, 0.0],
+            waveform: Waveform::Sine,
+            base_position: Vec3::new(0.0, 0.0, 0.0),
+        }];
+        let params = EngineParams::default();
+        let mut engine = MusicEngine::new(configs, params, 1);
+        engine.set_voice_position(0, Vec3::new(2.0, 0.0, -1.0));
+        assert_eq!(engine.voices[0].position, Vec3::new(2.0, 0.0, -1.0));
+    }
     fn midi_to_hz_references() {
         assert!(approx_eq(midi_to_hz(69.0), 440.0, 0.01));
         // Middle C ≈ 261.6256 Hz

crates/app-web/src/input.rs

@@ -0,0 +1,30 @@
+use glam::Vec3;
+
+#[derive(Default, Clone, Copy)]
+pub struct MouseState {
+    pub x: f32,
+    pub y: f32,
+    pub down: bool,
+}
+#[derive(Default, Clone, Copy)]
+pub struct DragState {
+    pub active: bool,
+    pub voice: usize,
+    pub plane_z_world: f32,
+}
+#[inline]
+pub fn ray_sphere(ray_origin: Vec3, ray_dir: Vec3, center: Vec3, radius: f32) -> Option<f32> {
+    let oc = ray_origin - center;
+    let b = oc.dot(ray_dir);
+    let c = oc.dot(oc) - radius * radius;
+    let disc = b * b - c;
+    if disc < 0.0 {
+        return None;
+    }
+    let t = -b - disc.sqrt();
+    if t >= 0.0 {
+        Some(t)
+    } else {
+        None
+    }
+}

crates/app-web/src/lib.rs

@@ -15,6 +15,10 @@ use wasm_bindgen_futures::spawn_local;
 use web_sys as web;
 // (DeviceExt no longer needed; legacy vertex buffers removed)
 
+mod input;
+mod render;
+mod ui;
+
 // Rendering/picking shared constants to keep math consistent
 const CAMERA_Z: f32 = 6.0;
 
@@ -52,25 +56,7 @@ async fn init() -> anyhow::Result<()> {
         let closure = Closure::wrap(Box::new(move |ev: web::KeyboardEvent| {
             let key = ev.key();
             if key == "h" || key == "H" {
-                if let Ok(Some(el)) = document.query_selector(".hint") {
-                    let cur = el.get_attribute("data-visible");
-                    let show = match cur.as_deref() {
-                        Some("1") => false,
-                        _ => true,
-                    };
-                    let _ = el.set_attribute("data-visible", if show { "1" } else { "0" });
-                    if let Some(div) = el.dyn_ref::<web::HtmlElement>() {
-                        if show {
-                            // Default content (before full engine/UI attach)
-                            div.set_inner_html(
-                                "Click Start to begin • Drag to move a voice\nClick: mute • Shift+Click: reseed • Alt+Click: solo\nR: reseed all • Space: pause/resume • +/-: tempo\nBPM: 110 • Paused: no",
-                            );
-                            let _ = el.set_attribute("style", "");
-                        } else {
-                            let _ = el.set_attribute("style", "display:none");
-                        }
-                    }
-                }
+                ui::toggle_hint_visibility(&document);
                 ev.prevent_default();
             }
         }) as Box<dyn FnMut(_)>);
@@ -475,39 +461,9 @@ async fn init() -> anyhow::Result<()> {
                         Rc::new(RefCell::new(None));
 
                     // ---------------- Interaction state ----------------
-                    #[derive(Default, Clone, Copy)]
-                    struct MouseState {
-                        x: f32,
-                        y: f32,
-                        down: bool,
-                    }
-                    #[derive(Default, Clone, Copy)]
-                    struct DragState {
-                        active: bool,
-                        voice: usize,
-                        plane_z_world: f32,
-                    }
-                    let mouse_state = Rc::new(RefCell::new(MouseState::default()));
+                    let mouse_state = Rc::new(RefCell::new(input::MouseState::default()));
                     let hover_index = Rc::new(RefCell::new(None::<usize>));
-                    let drag_state = Rc::new(RefCell::new(DragState::default()));
-
-                    // Ray-sphere intersect
-                    let ray_sphere =
-                        |ray_o: Vec3, ray_d: Vec3, center: Vec3, radius: f32| -> Option<f32> {
-                            let oc = ray_o - center;
-                            let b = oc.dot(ray_d);
-                            let c = oc.dot(oc) - radius * radius;
-                            let disc = b * b - c;
-                            if disc < 0.0 {
-                                return None;
-                            }
-                            let t = -b - disc.sqrt();
-                            if t >= 0.0 {
-                                Some(t)
-                            } else {
-                                None
-                            }
-                        };
+                    let drag_state = Rc::new(RefCell::new(input::DragState::default()));
 
                     // Screen -> canvas coords inline helper
 
@@ -542,37 +498,19 @@ async fn init() -> anyhow::Result<()> {
                             ms.y = pos.y;
                             // noisy move debug log removed
                             // Compute hover or drag update
-                            let width = canvas_mouse.width() as f32;
-                            let height = canvas_mouse.height() as f32;
-                            let ndc_x = (2.0 * pos.x / width) - 1.0;
-                            let ndc_y = 1.0 - (2.0 * pos.y / height);
-                            let aspect = width / height.max(1.0);
-                            let proj = Mat4::perspective_rh(
-                                std::f32::consts::FRAC_PI_4,
-                                aspect,
-                                0.1,
-                                100.0,
-                            );
-                            let view = Mat4::look_at_rh(
-                                Vec3::new(0.0, 0.0, CAMERA_Z),
-                                Vec3::ZERO,
-                                Vec3::Y,
+                            let (ro, rd) = render::screen_to_world_ray(
+                                &canvas_mouse,
+                                pos.x,
+                                pos.y,
+                                CAMERA_Z,
                             );
-                            let inv = (proj * view).inverse();
-                            let p_near = inv * Vec4::new(ndc_x, ndc_y, 0.0, 1.0);
-                            let p_far = inv * Vec4::new(ndc_x, ndc_y, 1.0, 1.0);
-                            let _p0: Vec3 = p_near.truncate() / p_near.w;
-                            let p1: Vec3 = p_far.truncate() / p_far.w;
-                            // Ray origin from camera eye to improve drag intersection stability
-                            let ro = Vec3::new(0.0, 0.0, CAMERA_Z);
-                            let rd = (p1 - ro).normalize();
                             let mut best = None::<(usize, f32)>;
                             let spread = SPREAD;
                             let z_offset = z_offset_vec3();
                             for (i, v) in engine_m.borrow().voices.iter().enumerate() {
                                 let center_world = v.position * spread + z_offset;
                                 if let Some(t) =
-                                    ray_sphere(ro, rd, center_world, PICK_SPHERE_RADIUS)
+                                    input::ray_sphere(ro, rd, center_world, PICK_SPHERE_RADIUS)
                                 {
                                     if t >= 0.0 {
                                         match best {