feat: add live speed control and sorting step explanations

[TrendMYX]

🚀 Pull Request

⭐ Repository Support

Have you starred the repository?

• ⭐ Yes, I have starred the repository
• ❌ No, I will star it now → Click here to star

💡 Why star? Stars help increase project visibility and show your support for the project!

📝 Description

What does this PR do?
This PR improves the sorting visualizer learning experience by adding live
animation speed updates and a detailed step explanation panel.

Users can now adjust animation speed while a sorting algorithm is already
running, without stopping or restarting the visualization. The PR also adds a
learning panel that explains the active algorithm, current highlighted values,
decision rule, highlight meaning, algorithm walkthrough, and next step in a
compact L-shaped layout around the visualization.

Related Issue(s):

Relates to sorting visualizer learning experience and animation controls

• Relates to Add Step-by-Step Explanation Mode Alongside Sorting Visualization #710, [PERF] : Dynamic Speed Control During Sorting Visualization #657, [FEATURE] Add "Step-by-Step Mode" for Sorting Visualizations #655

🔄 Type of Change

Please delete options that are not relevant:

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 Documentation update
• 🎨 Style/UI improvement
• ⚡ Performance optimization
• 🧹 Code refactoring
• 🧪 Test addition/improvement
• 🔧 Build/CI configuration
• 🌐 Accessibility improvement

🛠️ Changes Made

Core Changes

• Algorithm implementation/improvement
• UI/UX enhancements
• Performance optimizations
• Bug fixes
• Documentation updates

Detailed Changes

1. Live animation speed updates: Added delayRef support so sorting
   delays can read the latest speed value during an active visualization run.
2. Sorting algorithm integration: Passed the live speed reference through
   the sorting controller, runner, shared sorting controls, and all visualized
   sorting algorithms.
3. Improved speed controls: Kept the speed slider and speed adjustment
   buttons enabled during sorting so users can change animation delay in real
   time.
4. Step explanation panel: Added a beginner-friendly explanation system
   that describes the active algorithm, highlighted values, decision rule,
   highlight meaning, algorithm walkthrough, and next step.
5. Compact learning layout: Placed the explanation UI around the
   visualization using a compact L-shaped layout, with the current step on the
   side and detailed learning sections below.
6. Tests: Added unit tests for live delay updates and sorting step
   explanation behavior.

Files Modified

• SortVision/src/algorithms/types.ts - Added SortDelayRef and updated
  sorting algorithm types to support live delay references.
• SortVision/src/algorithms/sleep.ts - Updated delayStep to read the
  latest delay from delayRef.current while waiting.
• SortVision/src/algorithms/bubbleSort.ts - Passed live delay references
  into visualization delays.
• SortVision/src/algorithms/bucketSort.ts - Passed live delay references
  into visualization delays.
• SortVision/src/algorithms/heapSort.ts - Passed live delay references into
  visualization delays.
• SortVision/src/algorithms/insertionSort.ts - Passed live delay references
  into visualization delays.
• SortVision/src/algorithms/mergeSort.ts - Passed live delay references into
  visualization delays.
• SortVision/src/algorithms/quickSort.ts - Passed live delay references into
  visualization delays.
• SortVision/src/algorithms/radixSort.ts - Passed live delay references into
  visualization delays.
• SortVision/src/algorithms/selectionSort.ts - Passed live delay references
  into visualization delays.
• SortVision/src/algorithms/sleep.test.ts - Added coverage for updated delay
  behavior.
• SortVision/src/components/panels/config/SpeedControl.tsx - Allowed speed
  controls to remain usable during active sorting.
• SortVision/src/components/panels/ConfigPanel/ConfigPanel.tsx - Added the
  step explanation panel to the sorting visualizer layout.
• SortVision/src/components/sortingVisualizer/SortingControls.tsx - Passed
  the live speed reference into algorithm runners.
• SortVision/src/components/sortingVisualizer/hooks/useSortingController.ts
• Added and synchronized speedRef with the latest selected speed.
• SortVision/src/components/sortingVisualizer/hooks/useSortingRunner.ts -
  Passed speedRef through start and test-all sorting flows.
• SortVision/src/components/sortingVisualizer/stepExplanation.ts - Added
  explanation generation logic for supported sorting algorithms.
• SortVision/src/components/sortingVisualizer/components/ StepExplanationPanel.tsx - Added the learning UI panel for current step and
  algorithm guidance.
• SortVision/src/components/sortingVisualizer/stepExplanation.test.ts -
  Added tests for step explanation output.

🎯 Sorting Algorithms (if applicable)

Algorithm(s) affected:

• Bubble Sort
• Bucket Sort
• Heap Sort
• Insertion Sort
• Merge Sort
• Quick Sort
• Radix Sort
• Selection Sort
• Tim Sort
• Other: **___**

Algorithm improvements:

• Time complexity optimization
• Space complexity optimization
• Visualization enhancement
• Code readability improvement
• Bug fix in implementation

🧪 Testing

Manual Testing

• All sorting algorithms work correctly
• UI components render properly
• Animations are smooth and accurate
• Responsive design works on different screen sizes
• Performance is acceptable with large datasets

Test Cases

• Added new test cases
• Updated existing test cases
• All tests pass locally
• No regression in existing functionality

Testing Checklist

• Tested on Desktop (Chrome/Firefox/Safari)
• Tested on Mobile (iOS/Android)
• Tested with different array sizes (10, 100, 500+ elements)
• Tested edge cases (empty array, single element, already sorted)
• Tested performance with large datasets

⚡ Performance Impact

• No performance impact
• Improves performance
• May affect performance (explain below)

🔗 Dependencies

New Dependencies Added

• No new dependencies
• Production dependencies: dependency-name@version
• Development dependencies: dependency-name@version

Breaking Changes

• No breaking changes
• Breaking changes (describe below)

✅ Checklist

Code Quality

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings or errors
• I have added tests that prove my fix is effective or that my feature works

Git Hygiene

• My commits are atomic and have descriptive messages
• I have rebased/merged the latest main branch
• I have resolved any merge conflicts

Project Specific

• All sorting algorithms maintain their correctness
• Visual representations are accurate
• Performance is not degraded
• Accessibility standards are maintained
• Mobile responsiveness is preserved

[vercel]

@TrendMYX is attempting to deploy a commit to the alienx99 Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sortvision	Ready	Preview, Comment	May 17, 2026 1:19pm