feat(core): microtonal detune support + hint overlay updates; fix borrow panics in browser by reducing RefCell lifetimes and snapshotting state; add logs for keys/clicks to satisfy headless test; update tests for detune accuracy

Author: rgilks

index.html

@@ -170,6 +170,8 @@ <h3>Keys</h3>
                 <li><span class="kbd">R</span>: new sequence</li>
                 <li><span class="kbd">T</span>: random root + mode</li>
                 <li><span class="kbd">Space</span>: pause/resume</li>
+                <li><span class="kbd">,</span>/<span class="kbd">.</span>: detune ±50¢ (Shift for ±10¢)</li>
+                <li><span class="kbd">/</span>: reset detune to 0¢</li>
                 <li>
                   <span class="kbd">Enter</span>/<span class="kbd">Esc</span>:
                   full/exit screen
@@ -215,6 +217,16 @@ <h3>Modes (1..7)</h3>
       </div>
     </div>
     <canvas id="app-canvas" width="1280" height="720"></canvas>
+    <div
+      id="hint-overlay"
+      style="
+        position: fixed;
+        left: 12px;
+        top: 12px;
+        z-index: 5;
+        display: none;
+      "
+    ></div>
     <div
       id="audio-error"
       style="

src/core/music.rs

@@ -57,11 +57,13 @@ pub struct VoiceState {
 /// - `bpm` controls the tempo of the scheduler (beats per minute)
 /// - `scale` is the allowed pitch degree set, expressed as semitone offsets
 /// - `root_midi` is the MIDI note number of the tonal center (e.g., 60 for C4)
+/// - `detune_cents` is the global detune offset in cents (-200 to +200)
 #[derive(Clone, Debug)]
 pub struct EngineParams {
     pub bpm: f32,
     pub scale: &'static [i32],
     pub root_midi: i32,
+    pub detune_cents: f32,
 }
 
 impl Default for EngineParams {
@@ -70,6 +72,7 @@ impl Default for EngineParams {
             bpm: 110.0,
             scale: C_MAJOR_PENTATONIC,
             root_midi: 60, // Middle C
+            detune_cents: 0.0,
         }
     }
 }
@@ -141,6 +144,24 @@ impl MusicEngine {
         self.params.bpm = bpm;
     }
 
+    /// Set the global detune offset in cents.
+    /// Range: -200 to +200 cents (±2 semitones)
+    pub fn set_detune_cents(&mut self, detune_cents: f32) {
+        self.params.detune_cents = detune_cents.clamp(-200.0, 200.0);
+    }
+
+    /// Adjust the global detune offset by the specified amount in cents.
+    /// The result is clamped to the valid range of -200 to +200 cents.
+    pub fn adjust_detune_cents(&mut self, delta_cents: f32) {
+        let new_detune = self.params.detune_cents + delta_cents;
+        self.set_detune_cents(new_detune);
+    }
+
+    /// Reset the global detune offset to 0 cents (no detune).
+    pub fn reset_detune(&mut self) {
+        self.params.detune_cents = 0.0;
+    }
+
     /// 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) {
@@ -205,7 +226,7 @@ impl MusicEngine {
                 let degree = *self.params.scale.choose(rng).unwrap_or(&0);
                 let octave = self.configs[i].octave_offset;
                 let midi = self.params.root_midi + degree + octave * 12;
-                let freq = midi_to_hz(midi as f32);
+                let freq = midi_to_hz_with_detune(midi as f32, self.params.detune_cents);
                 let vel = 0.4 + rng.gen::<f32>() * 0.6;
                 let dur = self.configs[i].base_duration + rng.gen::<f32>() * 0.2;
                 out_events.push(NoteEvent {
@@ -222,6 +243,20 @@ impl MusicEngine {
 /// Convert a MIDI note number to Hertz (A4=440 Hz).
 ///
 /// Monotonic and exhibits octave symmetry: +12 semitones doubles the frequency.
+/// Supports fractional MIDI values for microtonal precision.
 pub fn midi_to_hz(midi: f32) -> f32 {
     440.0 * (2.0_f32).powf((midi - 69.0) / 12.0)
 }
+
+/// Convert a MIDI note number to Hertz with detune offset in cents.
+///
+/// The detune_cents parameter allows for microtonal adjustments:
+/// - Positive values raise the pitch (e.g., +50¢ = quarter tone sharp)
+/// - Negative values lower the pitch (e.g., -50¢ = quarter tone flat)
+/// - Range: -200 to +200 cents (±2 semitones)
+pub fn midi_to_hz_with_detune(midi: f32, detune_cents: f32) -> f32 {
+    let clamped_detune = detune_cents.clamp(-200.0, 200.0);
+    let detune_semitones = clamped_detune / 100.0;
+    let adjusted_midi = midi + detune_semitones;
+    midi_to_hz(adjusted_midi)
+}

src/events/keyboard.rs

@@ -1,10 +1,43 @@
 use crate::core::MusicEngine;
 use crate::core::{AEOLIAN, DORIAN, IONIAN, LOCRIAN, LYDIAN, MIXOLYDIAN, PHRYGIAN};
+use crate::overlay;
 use std::cell::RefCell;
 use std::rc::Rc;
 use wasm_bindgen::JsCast;
 use web_sys as web;
 
+/// Get the name of the current scale for display purposes
+fn get_scale_name(scale: &[i32]) -> &'static str {
+    match scale {
+        s if s == IONIAN => "Ionian (major)",
+        s if s == DORIAN => "Dorian",
+        s if s == PHRYGIAN => "Phrygian",
+        s if s == LYDIAN => "Lydian",
+        s if s == MIXOLYDIAN => "Mixolydian",
+        s if s == AEOLIAN => "Aeolian (minor)",
+        s if s == LOCRIAN => "Locrian",
+        _ => "Custom",
+    }
+}
+
+/// Update the hint overlay after engine parameter changes
+fn update_hint_after_change(engine: &Rc<RefCell<MusicEngine>>) {
+    if let Some(window) = web::window() {
+        if let Some(document) = window.document() {
+            let (detune, bpm, scale_name) = {
+                let eng = engine.borrow();
+                (
+                    eng.params.detune_cents,
+                    eng.params.bpm,
+                    get_scale_name(eng.params.scale),
+                )
+            };
+            overlay::update_hint(&document, detune, bpm, scale_name);
+            overlay::show_hint(&document);
+        }
+    }
+}
+
 #[inline]
 pub fn root_midi_for_key(key: &str) -> Option<i32> {
     match key {
@@ -43,10 +76,12 @@ pub fn handle_global_keydown(
     let key = ev.key();
     if let Some(midi) = root_midi_for_key(&key) {
         engine.borrow_mut().params.root_midi = midi;
+        update_hint_after_change(engine);
         return;
     }
     if let Some(scale) = mode_scale_for_digit(&key) {
         engine.borrow_mut().params.scale = scale;
+        update_hint_after_change(engine);
         return;
     }
     match key.as_str() {
@@ -56,6 +91,7 @@ pub fn handle_global_keydown(
             for i in 0..voice_len {
                 eng.reseed_voice(i, None);
             }
+            log::info!("[keys] reseeded all voices");
         }
         "t" | "T" => {
             let roots: [i32; 7] = [60, 62, 64, 65, 67, 69, 71]; // C, D, E, F, G, A, B
@@ -67,21 +103,54 @@ pub fn handle_global_keydown(
             let mut eng = engine.borrow_mut();
             eng.params.root_midi = roots[ri];
             eng.params.scale = modes[mi];
+            drop(eng);
+            update_hint_after_change(engine);
         }
         " " => {
             let mut p = paused.borrow_mut();
             *p = !*p;
+            log::info!("[keys] paused={}", *p);
             ev.prevent_default();
         }
         "ArrowRight" | "+" | "=" => {
             let mut eng = engine.borrow_mut();
             let new_bpm = (eng.params.bpm + 5.0).min(240.0);
             eng.set_bpm(new_bpm);
+            drop(eng);
+            update_hint_after_change(engine);
         }
         "ArrowLeft" | "-" | "_" => {
             let mut eng = engine.borrow_mut();
             let new_bpm = (eng.params.bpm - 5.0).max(40.0);
             eng.set_bpm(new_bpm);
+            drop(eng);
+            update_hint_after_change(engine);
+        }
+        "," => {
+            let mut eng = engine.borrow_mut();
+            if ev.shift_key() {
+                eng.adjust_detune_cents(-10.0); // Fine adjustment
+            } else {
+                eng.adjust_detune_cents(-50.0); // Coarse adjustment
+            }
+            drop(eng);
+            update_hint_after_change(engine);
+        }
+        "." => {
+            let mut eng = engine.borrow_mut();
+            if ev.shift_key() {
+                eng.adjust_detune_cents(10.0); // Fine adjustment
+            } else {
+                eng.adjust_detune_cents(50.0); // Coarse adjustment
+            }
+            drop(eng);
+            update_hint_after_change(engine);
+        }
+        "/" => {
+            let mut eng = engine.borrow_mut();
+            eng.reset_detune();
+            drop(eng);
+            update_hint_after_change(engine);
         }
         "Enter" => {
             if let Some(win) = web::window() {

src/events/pointer.rs

@@ -49,7 +49,8 @@ fn wire_pointermove(w: &InputWiring) {
         let mut best = None::<(usize, f32)>;
         let z_offset = Z_OFFSET;
 
-        for (i, v) in w.engine.borrow().voices.iter().enumerate() {
+        let engine_snapshot = w.engine.borrow();
+        for (i, v) in engine_snapshot.voices.iter().enumerate() {
             let center_world = v.position * SPREAD + z_offset;
 
             if let Some(t) = input::ray_sphere(ro, rd, center_world, PICK_SPHERE_RADIUS) {
@@ -79,8 +80,8 @@ fn wire_pointermove(w: &InputWiring) {
                         eng_pos.z *= scale;
                     }
 
-                    let mut eng = w.engine.borrow_mut();
                     let vi = w.drag_state.borrow().voice;
+                    let mut eng = w.engine.borrow_mut();
                     eng.set_voice_position(vi, glam::Vec3::new(eng_pos.x, 0.0, eng_pos.z));
                 }
             }
@@ -137,10 +138,13 @@ fn wire_pointerup(w: &InputWiring) {
             let alt = ev.alt_key();
             if alt {
                 w.engine.borrow_mut().toggle_solo(i);
+                log::info!("[click] solo voice {}", i);
             } else if shift {
                 w.engine.borrow_mut().reseed_voice(i, None);
+                log::info!("[click] reseed voice {}", i);
             } else {
                 w.engine.borrow_mut().toggle_mute(i);
+                log::info!("[click] toggle mute voice {}", i);
             }
         } else {
             let [uvx, uvy] = input::pointer_canvas_uv(&ev, &w.canvas);

src/frame.rs

@@ -98,8 +98,12 @@ impl<'a> FrameContext<'a> {
             );
 
             // Per-voice audio positioning and sends
+            let voice_positions_snapshot: Vec<Vec3> = {
+                let eng = self.engine.borrow();
+                eng.voices.iter().map(|v| v.position).collect()
+            };
             for i in 0..self.voice_panners.len() {
-                let pos = self.engine.borrow().voices[i].position;
+                let pos = voice_positions_snapshot[i];
                 self.voice_panners[i].position_x().set_value(pos.x as f32);
                 self.voice_panners[i].position_y().set_value(pos.y as f32);
                 self.voice_panners[i].position_z().set_value(pos.z as f32);

src/lib.rs

@@ -76,6 +76,7 @@ async fn build_audio_and_engine(_document: web::Document) -> anyhow::Result<Init
             bpm: 110.0,
             scale: C_MAJOR_PENTATONIC,
             root_midi: 60,
+            detune_cents: 0.0,
         },
         42,
     )));

src/overlay.rs

@@ -42,3 +42,32 @@ pub fn toggle(document: &web::Document) {
         hide(document);
     }
 }
+
+/// Update the hint overlay with current engine state
+pub fn update_hint(document: &web::Document, detune_cents: f32, bpm: f32, scale_name: &str) {
+    if let Some(el) = document.get_element_by_id("hint-overlay") {
+        let detune_text = if detune_cents.abs() < 0.1 {
+            "Detune: 0¢".to_string()
+        } else {
+            let sign = if detune_cents > 0.0 { "+" } else { "" };
+            format!("Detune: {}{:.0}¢", sign, detune_cents)
+        };
+
+        let bpm_text = format!("BPM: {:.0}", bpm);
+        let scale_text = format!("Scale: {}", scale_name);
+
+        let hint_html = format!(
+            "<div style='color: #cfe7ff; font: 13px system-ui; background: rgba(10, 14, 24, 0.8); padding: 8px 12px; border-radius: 6px; border: 1px solid rgba(80, 110, 150, 0.35);'>{} • {} • {}</div>",
+            detune_text, bpm_text, scale_text
+        );
+
+        el.set_inner_html(&hint_html);
+    }
+}
+
+/// Show the hint overlay
+pub fn show_hint(document: &web::Document) {
+    if let Some(el) = document.get_element_by_id("hint-overlay") {
+        el.set_attribute("style", "").ok();
+    }
+}