fix: correct fractional_beat calculation to always use finest level

The fractional_beat should always represent the position within the finest
hierarchical level unit (between pulses), regardless of the reference_level
parameter. The reference_level only affects hierarchical_position truncation.

Fixed examples:
- meter.get_musical_time(0.125) now returns C0:0.2+0.000 (was C0:0.2+0.500)
- meter.get_musical_time(0.0625) now returns C0:0.1+0.000 (was C0:0.1+0.250)
- meter.get_musical_time(0.03125) now returns C0:0.0+0.500 (was C0:0.0+0.125)

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: jon-myers

idtap/classes/meter.py

@@ -575,9 +575,14 @@ def get_musical_time(self, real_time: float, reference_level: Optional[int] = No
                 remaining_time = remaining_time % subdivision_duration
 
         # Step 4: Fractional beat calculation
-        if ref_level == len(self.hierarchy) - 1:
-            # Default behavior: pulse-based calculation
-            current_pulse_index = self._hierarchical_position_to_pulse_index(positions, cycle_number)
+        # ALWAYS calculate fractional_beat as position within finest level unit (between pulses)
+        # This is independent of reference_level, which only affects hierarchical_position truncation
+        current_pulse_index = self._hierarchical_position_to_pulse_index(positions, cycle_number)
+        
+        # Bounds checking
+        if current_pulse_index < 0 or current_pulse_index >= len(self.all_pulses):
+            fractional_beat = 0.0
+        else:
             current_pulse_time = self.all_pulses[current_pulse_index].real_time
 
             # Handle next pulse
@@ -594,33 +599,16 @@ def get_musical_time(self, real_time: float, reference_level: Optional[int] = No
             else:
                 time_from_current_pulse = real_time - current_pulse_time
                 fractional_beat = time_from_current_pulse / pulse_duration
-            
-            # Clamp to [0, 1] range
-            fractional_beat = max(0.0, min(1.0, fractional_beat))
-            
-        else:
-            # Reference level behavior - preserve full positions for fractional_beat calculation
-            # but truncate for final result
-            truncated_positions = positions[:ref_level + 1]
-            
-            # Use full positions for accurate fractional_beat calculation
-            # This prevents clustering when reference_level=0 (Issue #28)
-            current_level_start_time = self._calculate_level_start_time(positions, cycle_number, ref_level)
-            level_duration = self._calculate_level_duration(positions, cycle_number, ref_level)
-            
-            if level_duration <= 0:
-                fractional_beat = 0.0
-            else:
-                time_from_level_start = real_time - current_level_start_time
-                fractional_beat = time_from_level_start / level_duration
-            
-            # Clamp to [0, 1] range
-            fractional_beat = max(0.0, min(1.0, fractional_beat))
-            
-            # Update positions to only include levels up to reference for final result
-            positions = truncated_positions
 
-        # Step 5: Result construction
+        # Clamp to [0, 1] range
+        fractional_beat = max(0.0, min(1.0, fractional_beat))
+        
+        # Step 5: Handle reference level truncation (if specified)
+        if ref_level is not None and ref_level < len(self.hierarchy) - 1:
+            # Truncate positions to reference level for final result
+            positions = positions[:ref_level + 1]
+        
+        # Step 6: Result construction
         return MusicalTime(
             cycle_number=cycle_number,
             hierarchical_position=positions,

idtap/tests/musical_time_test.py

@@ -93,13 +93,13 @@ def test_reference_level_beat(self):
         """Test Case 2 from spec: Reference level at beat level."""
         meter = Meter(hierarchy=[4, 4], tempo=240, start_time=0, repetitions=2)
 
-        result = meter.get_musical_time(1.375, reference_level=0)  # Within bounds: 1.375 = beat 1, 37.5% through beat
+        result = meter.get_musical_time(1.375, reference_level=0)  # 1.375s = 2nd cycle, beat 1, subdivision 2 (exactly on pulse)
 
         assert result is not False
         assert result.cycle_number == 1  # Second cycle
-        assert result.hierarchical_position == [1]  # Only beat level (beat 2)
-        assert abs(result.fractional_beat - 0.5) < 0.1  # 50% through beat 2
-        assert "C1:1+" in str(result)
+        assert result.hierarchical_position == [1]  # Only beat level (beat 2) due to reference_level=0
+        assert abs(result.fractional_beat - 0.0) < 0.01  # Exactly on pulse (fractional_beat always pulse-based)
+        assert str(result) == "C1:1+0.000"
 
     def test_reference_level_subdivision(self):
         """Test Case 3 from spec: Reference level at subdivision level."""
@@ -113,6 +113,26 @@ def test_reference_level_subdivision(self):
         assert abs(result.fractional_beat - 0.0) < 0.01  # Exactly on subdivision
         assert str(result) == "C0:1.2+0.000"
 
+    def test_johns_specific_examples(self):
+        """Test Jon's specific examples that revealed the fractional_beat calculation issue."""
+        meter = Meter(hierarchy=[4, 4], tempo=240, start_time=0, repetitions=3)
+        
+        # These examples should work correctly after the fix
+        result = meter.get_musical_time(0.5)
+        assert str(result) == "C0:2.0+0.000", f"Expected C0:2.0+0.000, got {result}"
+        
+        result = meter.get_musical_time(0.25)
+        assert str(result) == "C0:1.0+0.000", f"Expected C0:1.0+0.000, got {result}"
+        
+        result = meter.get_musical_time(0.125)
+        assert str(result) == "C0:0.2+0.000", f"Expected C0:0.2+0.000, got {result}"
+        
+        result = meter.get_musical_time(0.0625)
+        assert str(result) == "C0:0.1+0.000", f"Expected C0:0.1+0.000, got {result}"
+        
+        result = meter.get_musical_time(0.03125)
+        assert str(result) == "C0:0.0+0.500", f"Expected C0:0.0+0.500, got {result}"
+    
     def test_complex_hierarchy(self):
         """Test Case 4 from spec: Complex hierarchy with reference levels."""
         meter = Meter(hierarchy=[3, 2, 4], tempo=480, start_time=0, repetitions=1)  # Slower tempo