Comprehensive documentation and code cleanup for Steps mode

DOCUMENTATION ADDED:
- Detailed Steps mode documentation in code comments explaining microrhythm functionality
- README.md: New "Pattern Timing Modes" section with Steps/Beats/Bars explanations
- CLAUDE.md: Complete Steps mode implementation history and technical details
- Subdivision parameter documentation with beat fraction examples

CODE CLEANUP:
- Removed unused variable currentBPMInt causing compiler warnings
- Removed duplicate rotatePatternBySteps() function - replaced with UPIParser::rotatePattern()
- Eliminated function duplication and improved code maintainability
- Debug file I/O already disabled for production performance

STEPS MODE DOCUMENTATION:
- Function: Each step = subdivision (16th, 8th, 8th triplet, etc.)
- Pattern length completely ignored in Steps mode
- Formula: subdivision_duration × pattern_steps = total_duration
- Examples: 8×16th=2beats, 9×8th=4.5beats, 9×8th_triplet=3beats
- Use case: Microrhythmic variations by changing subdivision

Code is now well-documented and cleaned for other developers.

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

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

Author: Enkerli

CLAUDE.md

@@ -21,6 +21,31 @@
 
 ## Recent Issues Resolved  
 
+### CRITICAL: Steps Mode Implementation (July 2025)
+**Problem**: Steps mode was broken - step indicator jumped around and subdivision parameter had no effect.
+
+**Root Cause**: Multiple issues:
+1. Two different Steps mode calculations with inconsistent logic
+2. Main timing calculation used old logic: `patternLengthInBeats = lengthValue / 4.0` (wrong)  
+3. Transport sync used correct logic: `patternLengthInBeats = subdivisionBeatsPerStep * patternSteps` (right)
+4. Step calculation used wrong modulo approach causing jumping
+
+**Solution**: 
+1. **Unified Steps Mode Logic**: Both main and transport calculations now use identical logic
+2. **Pattern Length Ignored**: In Steps mode, pattern length value is completely ignored
+3. **Subdivision Control**: Each step represents selected subdivision (16th, 8th, 8th triplet, etc.)
+4. **Fixed Step Calculation**: Used `fmod()` for proper pattern cycling instead of integer modulo
+5. **Removed Debug File I/O**: Eliminated performance-killing debug operations from audio callbacks
+
+**Steps Mode Formula**: `total_pattern_duration = subdivision_duration × pattern_steps`
+
+**Examples**:
+- 8 steps × 16th notes = 8 × 0.25 = 2 beats (half note duration)
+- 9 steps × 8th notes = 9 × 0.5 = 4.5 beats total
+- 9 steps × 8th triplets = 9 × (1/3) = 3 beats total
+
+**Result**: Steps mode now provides proper "microrhythm" functionality where the same pattern can be played at different rhythmic resolutions.
+
 ### CRITICAL: MIDI Trigger Logic Fix (July 2025)
 **Problem**: Patterns with both progressive transformations and scenes (like `{1000000}E(1,16)E>16|1010101010101010`) only triggered progressive transformations via MIDI input, never advancing to scenes, unlike Enter key behavior.
 

Plugin/Source/PluginProcessor.cpp

@@ -220,7 +220,6 @@ void RhythmPatternExplorerAudioProcessor::processBlock (juce::AudioBuffer<float>
 
     // Log every 50 calls or when BPM changes, with focus on 200+ BPM
     debugCallCount++;
-    int currentBPMInt = static_cast<int>(currentBPM);
 
     // More frequent logging at high BPMs
     bool shouldLog = false;
@@ -378,6 +377,19 @@ void RhythmPatternExplorerAudioProcessor::processBlock (juce::AudioBuffer<float>
         switch (lengthUnit) {
             case 0: // Steps mode - each step represents a subdivision, pattern length is IGNORED
             {
+                // STEPS MODE DOCUMENTATION:
+                // In Steps mode, each step represents a specific subdivision (16th, 8th, 8th triplet, etc.)
+                // The subdivision parameter determines what each step represents.
+                // Pattern length value is completely ignored - only subdivision and pattern size matter.
+                //
+                // Examples:
+                // - 8 steps × 16th notes = 8 × 0.25 = 2 beats total (half note duration)
+                // - 9 steps × 8th notes = 9 × 0.5 = 4.5 beats total  
+                // - 9 steps × 8th triplets = 9 × (1/3) = 3 beats total
+                //
+                // This creates "microrhythm" functionality where the same pattern can be
+                // played at different rhythmic resolutions by changing the subdivision.
+                
                 // Convert subdivision index to beat fraction per step
                 double subdivisionBeatsPerStep = getSubdivisionInBeats(subdivisionIndex);
 
@@ -743,6 +755,7 @@ void RhythmPatternExplorerAudioProcessor::syncPositionWithHost(const juce::Audio
         switch (lengthUnit) {
             case 0: // Steps mode - each step represents a subdivision, pattern length is IGNORED
             {
+                // Steps mode: Same logic as main calculation - subdivision determines step duration
                 double subdivisionBeatsPerStep = getSubdivisionInBeats(subdivisionIndex);
                 patternLengthInBeats = subdivisionBeatsPerStep * patternSteps;
 
@@ -969,7 +982,7 @@ void RhythmPatternExplorerAudioProcessor::setUPIInput(const juce::String& upiPat
         if (progressiveOffset != 0)
         {
             auto currentPattern = patternEngine.getCurrentPattern();
-            auto rotatedPattern = rotatePatternBySteps(currentPattern, progressiveOffset);
+            auto rotatedPattern = UPIParser::rotatePattern(currentPattern, progressiveOffset);
             patternEngine.setPattern(rotatedPattern);
 
             // Debug log rotation
@@ -1253,26 +1266,6 @@ void RhythmPatternExplorerAudioProcessor::checkMidiInputForTriggers(juce::MidiBu
     }
 }
 
-std::vector<bool> RhythmPatternExplorerAudioProcessor::rotatePatternBySteps(const std::vector<bool>& pattern, int steps)
-{
-    if (pattern.empty()) 
-        return pattern;
-    
-    std::vector<bool> rotated(pattern.size());
-    int size = static_cast<int>(pattern.size());
-    
-    // Normalize steps to be within pattern size
-    steps = steps % size;
-    if (steps < 0) steps += size;
-    
-    for (int i = 0; i < size; ++i)
-    {
-        int newIndex = (i + steps) % size;
-        rotated[newIndex] = pattern[i];
-    }
-    
-    return rotated;
-}
 
 void RhythmPatternExplorerAudioProcessor::advanceProgressiveLengthening()
 {
@@ -1379,7 +1372,7 @@ void RhythmPatternExplorerAudioProcessor::applyCurrentScenePattern()
     {
         // Apply progressive offset by rotating the generated pattern
         auto currentPattern = patternEngine.getCurrentPattern();
-        auto rotatedPattern = rotatePatternBySteps(currentPattern, progressiveOffset);
+        auto rotatedPattern = UPIParser::rotatePattern(currentPattern, progressiveOffset);
         patternEngine.setPattern(rotatedPattern);
 
         logDebug(DebugCategory::SCENE_CYCLING, 
@@ -1503,8 +1496,19 @@ float RhythmPatternExplorerAudioProcessor::getPatternLengthValue() const
 
 double RhythmPatternExplorerAudioProcessor::getSubdivisionInBeats(int subdivisionIndex) const
 {
-    // Convert subdivision choice to beat fractions
+    // SUBDIVISION PARAMETER DOCUMENTATION:
+    // This function converts subdivision parameter choices to beat fractions for Steps mode.
+    // Each subdivision represents how much of a beat one step occupies.
+    //
     // Subdivision choices: {"64th Triplet", "64th", "32nd Triplet", "32nd", "16th Triplet", "16th", "8th Triplet", "8th", "Quarter Triplet", "Quarter", "Half Triplet", "Half", "Whole"}
+    // Default: index 5 = "16th" = 0.25 beats per step
+    //
+    // Examples:
+    // - 16th notes: 0.25 beats per step (4 steps = 1 beat)
+    // - 8th notes: 0.5 beats per step (2 steps = 1 beat)  
+    // - 8th triplets: 1/3 beats per step (3 steps = 1 beat)
+    // - Quarter notes: 1.0 beats per step (1 step = 1 beat)
+    
     static const double subdivisionBeats[] = {
         1.0/24.0,  // 64th Triplet (1/64 * 2/3 = 1/96, but musically 1/24 makes more sense)
         1.0/16.0,  // 64th

Plugin/Source/PluginProcessor.h

@@ -290,7 +290,6 @@ class RhythmPatternExplorerAudioProcessor  : public juce::AudioProcessor
     static const char* getLogFile(DebugCategory category);
 
     // Pattern manipulation
-    std::vector<bool> rotatePatternBySteps(const std::vector<bool>& pattern, int steps);
     std::vector<bool> generateBellCurveRandomSteps(int numSteps);
     std::vector<bool> lengthenPattern(const std::vector<bool>& pattern, int additionalSteps);
 

README.md

@@ -87,6 +87,36 @@ python3 -m http.server 8000
 - **Visual Feedback**: Red for accented onsets, green for regular onsets
 - **Universal Support**: Works with all pattern types (E, P, R, B, W, D)
 
+### Pattern Timing Modes (v0.03e+)
+Three distinct modes for controlling pattern timing and duration:
+
+#### **Steps Mode** (Microrhythm Control)
+- **Function**: Each step represents a specific subdivision (16th, 8th, 8th triplet, etc.)
+- **Subdivision Parameter**: Determines what each step represents
+- **Pattern Length**: **Completely ignored** - only subdivision and pattern size matter
+- **Calculation**: `subdivision_duration × pattern_steps = total_duration`
+
+**Examples:**
+```
+8 steps × 16th notes = 8 × 0.25 = 2 beats (half note duration)
+9 steps × 8th notes = 9 × 0.5 = 4.5 beats total
+9 steps × 8th triplets = 9 × (1/3) = 3 beats total
+```
+
+**Use Case**: Create microrhythmic variations by changing subdivision while keeping the same pattern.
+
+#### **Beats Mode** (Divisive Timing)
+- **Function**: Pattern fits exactly within specified number of beats
+- **Pattern Length**: Determines total duration in beats
+- **Calculation**: `pattern_fits_in_X_beats`
+- **Use Case**: Ensure patterns align with specific beat durations
+
+#### **Bars Mode** (Metric Timing)  
+- **Function**: Pattern fits exactly within specified number of bars (assumes 4/4 time)
+- **Pattern Length**: Determines total duration in bars
+- **Calculation**: `pattern_fits_in_X_bars × 4_beats_per_bar`
+- **Use Case**: Create patterns that span multiple bars precisely
+
 ### UPI (Universal Pattern Input) Notation
 
 #### Basic Pattern Generation